JSON:API Interface

[kyohah]

In JSON:API pagination example

GET /articles?page[number]=3&page[size]=1 HTTP/1.1

Rails controller

params # => {"page"=>{"number"=>"1", "size" => 3} }

Pagy::VARS[:page_param] cannot set the number in hash.
Can't use pagy_metadata in JSON:API.

Pagy::VARS[:page_param] = "page[number]"
pagy_metadata(@pagy)
#=> {:scaffold_url=>"/articles?page[number]=3&page[size]=1&page%5Bnumber%5D=__pagy_page__",
 :first_url=>"/articles?page[number]=3&page[size]=1&page%5Bnumber%5D=1",
 :prev_url=>"/articles?page[number]=3&page[size]=1&page%5Bnumber%5D=",
 :page_url=>"/articles?page[number]=3&page[size]=1&page%5Bnumber%5D=1",
 :next_url=>"/articles?page[number]=3&page[size]=1&page%5Bnumber%5D=2",
 :last_url=>"/articles?page[number]=3&page[size]=1&page%5Bnumber%5D=6",

Related code

pagy/lib/pagy/frontend.rb

Line 18 in 49205fe

p_vars = pagy.vars; params = request.GET.merge(p_vars[:params]); params[p_vars[:page_param].to_s] = page

[curtis741]

@ddnexus What JsonApi wants to do here is this params['page']['number']. See https://jsonapi.org/format/#query-parameters-families for full details.

possible to reopen this?

[ddnexus]

Handling params with a different syntax could be done in an extension and in theory it could be relatively simple.

If anyone could prepare a minimal app showing the problem, I could take a look.

[ddnexus]

@kyohah @curtis741 @benkoshy anyone?

[benkoshy]

Sorry must have missed this one. I'll have to come back to this. From memory I suggested an adapter class to handle this, but it may not apply in this particular case.

Update - Notes to myself

• I found a gem which seems to address this use-case: https://www.useo.pl/blog/2021/03/introducing-jsom-pagination

• Here is the spec: https://jsonapi.org/format/#fetching-pagination

• Sample implementation: https://github.com/stas/jsonapi.rb#usage (ruby)

• https://github.com/scoutforpets/bookshelf-jsonapi-params (js)

• I am experimenting / hacking on a separate branch: https://github.com/benkoshy/pagy/tree/json-api-pagination as I study this problem.

[ddnexus]

It applies as a customization, but we might add an official extension if it's simple enough.

[ddnexus]

@kyohah @curtis741 @benkoshy

Ok, I am willing to implement this, but I need a few answers.

From your input I understand that the conventional way to pass the pagination params for JSON API would be passing nested query params under the 'page' root.

What I don't get from your input is whether that particular structure is required in order to be compliant with the convention or it's a technical matter of the structure used by another app/lib/class?

Should every pagy related param be put into the nested structure or just a well defined few? Do you have a list?

AFAIR pagy uses only the page number and the items (if you use the items extra). Besides the calendar extra uses one page param per time unit, but that extra makes little sense in json, so we can ignore it for the moment.

That params from the request are used for creating the pagy object, and are also used to generate the urls of each page. If they are the only params to take care of, it should be quite simple.

Please, let me know.

[benkoshy]

What I don't get from your input is whether that particular structure is required in order to be compliant with the convention or it's a technical matter of the structure used by another app/lib/class?

This my understanding is that in order to be compliant, you have to nest the pagination params.

Should every pagy related param be put into the nested structure or just a well defined few? Do you have a list?

https://jsonapi.org/format/#fetching-pagination

i.e. you must nest under the page parameter key. and you must have:

first: the first page of data
last: the last page of data
prev: the previous page of data
next: the next page of data

[ddnexus]

@benkoshy That are not query params, that are metadata. They follow the same principle applied for the "Link" header in the headers extra.

Currently you can manually compose the links for jsonapi using the metadata extra, but the real problem is the structure of the query params must be nested. We are talking about the page number (page) and the size (items) IN the URL links, not the links metadata themselves (first, last, prev, next) that must not be in the URL links.

If we are going to do a jsonapi extra, the links that the dev could add in their response will more conveniently be available as a single method, but the problem to solve now is the generation of the proper URLs to serve in the response and the extraction of the nested params from the request

[ddnexus]

The jsonapi branch seems to be working!