Pagination schema for codelists referential APIs

[kshychko]

There are different pagination schemas can be applied and we need to choose one a standard, so we use it for all APIs.

We could consider ones from Django rest framework - https://www.django-rest-framework.org/api-guide/pagination/#api-reference . The same strategies are mentioned in JSON API specification - https://jsonapi.org/format/#fetching-pagination

I would opt for offset strategy, but all of them are valid options.

[rgenoulaz]

That's an interesting question, we actually use a standard "HTTP approach" based on https://tools.ietf.org/html/rfc7233#section-4.1 .

It actually aplies quite well to our purpose, as explained here : http://otac0n.com/blog/2012/11/21/range-header-i-choose-you.html

What do you think ?

[Fak3]

Here is the perfect answer why we should not use range header: https://stackoverflow.com/questions/21765555/why-most-api-paginations-do-not-rely-on-http-range-header

Proxy servers and other middleware mess with it and the rfc allows for inconsistency to emerge:

I conform to the HTTP spec when I'm sending [a custom range unit] and they conform to HTTP when they ignore it WebDAV uses HTTP extensions correctly, IMO, but rarely works over the Internet for exactly this reason

there are example issues in the comments of the blogpost you linked

From RFC 7233:

A proxy MAY discard a Range header field that contains a range unit it does not understand.

[rgenoulaz]

Thank you @Fak3 for your feedback. This actually triggered an interesting debate back here :) I'll make a second proposition, please feel free to comment and propose an alternative.

1. First, I think there is no debate, we need to use an offset approach. (limit+ offset)

2. We need to decide where to put the pagination information in the request ==> I believe it makes more sense in the query : like /items?limit=20&offset=40

3. 2. We need to decide where to put the pagination information in the response ==> I'm OK not to use an existing Http header cause this might create somemore issues, but O do not want to store the information in the body of the response otherwise this will complicate the types that the API returns, for ce use to create a dedicated type with the pagination information for each method, and it would prevent us from returning a simple collections of objects (which would be a pity). Therefore I would propose to use custom HTTP Header like X-Range = ... except We should not prefix parameter names with "X-" or similar constructs (according to https://tools.ietf.org/html/rfc6648 apparently). SI let's say something like API-RANGE=...

What do you think ?

[cmsdroff]

I think the approach should be consistent across all API work from edi3 so maybe not just a code list issue, we should consider or re-pose the question and reference this ticket and useful comments in the #general slack channel, would you agree @rgenoulaz

[ecki]

What is also a problem is that the pagination scheme used is not part of the swagger schema. at least not the schema I have seen compared to the current hosted service.