Search code examples
json-api

jsonapi.org correct way to use pagination using the page query string

In the documentation for jsonapi for pagination is says the following:

For example, a page-based strategy might use query parameters such as page[number] and page[size]

How would I represent this in the query string? http://localhost:4200/people?page[number]=1&page[size]=25, I don't think using a map link structure is a valid query string. Only the page parameter is reserved according to the documentation.

Solution

  • I don't think using a map link structure is a valid query string.

    You're right technically, and that's why the spec has the note that says:

    Note: The example query parameters above use unencoded [ and ] characters simply for readability. In practice, these characters must be percent-encoded, per the requirements in RFC 3986.

    So, page[size] is really page%5Bsize%5D which is a valid query parameter name.

    Only the page parameter is reserved according to the documentation.

    When the spec text says that only page is reserved, it actually means that any page[......] style query parameter is reserved. (I can tell you that for sure as one of the spec's editors.) But it should say so more explicitly, so I'll open an issue for it.