Documenting JSON:API-style filter and page attributes

[strzibny]

So in JSON:API 1.0 specification the filter and page attributes are actually maps.

And the attributes themselves would be filter[attribute_name]=term or page[number]=2.

How to document this with Blueprint? Just keep filter[attribute_name] as attribute name?

[kylef]

I'm a little unsure if you mean parameters instead of attributes so I'll cover both below.

Parameters

For parameters, URI Template declares a set of reserved characters and when used they must be encoded, for example [ and ]. The particular part of URI Template RFC that delcares this is at https://tools.ietf.org/html/rfc6570#section-2.3:

 variable-list =  varspec *( "," varspec )
 varspec       =  varname [ modifier-level4 ]
 varname       =  varchar *( ["."] varchar )
 varchar       =  ALPHA / DIGIT / "_" / pct-encoded

varchar effectively declares which values may be permitted in a parameter name in API Blueprint. That is alphanumeric, digits, underscores and percent encoded values. Any names that cannot be described using that character set may be percent encoded.

This makes use of the referenced notinal conventions declared at https://tools.ietf.org/html/rfc6570#section-1.5.

The API Blueprint parser should give you a warning telling you this, and I believe it suggests which characters should be encoded and what they should be encoded as. Here's an example using reserved characters:

## Query [GET /{?filter%5Battribute_name%5D,page%5Bnumber%5D}]

+ Parameters
    + `filter%5Battribute_name%5D`: name
    + `page%5Bnumber%5D`: 2

+ Response 204

Tooling should decode the parameter name out of a URI context for human consumption, for example:

Attributes

As for attributes, I don't see any reason why you would have a problem using [ or ] in an attribute, the following seems to work correct to me:

+ Response 200 (application/json)
    + Attributes
        + `filter[attribute_name]`: term
        + `page[number]`: 2 (number)

Rendered as:

[strzibny]

Yes, I needed parameters. Great answer thanks a lot, I will try it and then close this issue:)