Cursor pagination profile: Link for next page in case of truncated range

[jelhan]

The cursor pagination profile allows clients to combine both page[after] and page[before] to request all resources in between both cursors. These are called range pagination requests.

The requested range may exceed the used page size. In that case the server returns with a truncated range.

If the number of results that satisfy both the page[after] and page[before] constraints exceeds the used page size, the server MUST respond with the same paginated data that it would have if the page[before] parameter had not been provided. However, in this case the server MUST also add "rangeTruncated": true to the pagination metadata to indicate to the client that the paginated data does not contain all the results it requested.

https://jsonapi.org/profiles/ethanresnick/cursor-pagination/#auto-id--combining-pageafter-and-pagebefore

This does not explicitly define what should be represented by the next link. There seems to be at least two options what the next link may represent in this case:

1. The next page of truncated data within the requested range.
2. The next page after the last resource included in the truncated data ignoring the requested range.

The examples included in the profile, do not include page[before] in the next link. That seems to indicate that the profile intended to specify the second option. But I think it should be clarified.

Pinging @ethanresnick as he wrote that profile initially. Not sure if it is still owned / maintained by him or by page editors. The status of that profile is unclear to me. See also #1527 in that regard.

[ethanresnick]

Hi @jelhan (and Dan!), I've obviously been absent from JSON:API for a while — life intervened ☹️ — but I do find myself still relying on this profile in various projects, so I'd be happy to keep it updated. I've actually fixed a couple issues over the years that I've discovered with the profile (including this issue and some other needed refinements to range pagination). I'd be happy to submit those fixes back to the JSON:API repo before this profile is officially marked as "stable", if you'd like.

To @jelhan's specific question, though, my intention was to specify option (1). That seems more useful to me -- otherwise, the truncated data would be totally inaccessible, right? -- but, if I'm missing something and (2) would be better for some reason, I'm very open to hearing the use case.

[jelhan]

Hi @jelhan (and Dan!), I've obviously been absent from JSON:API for a while — life intervened frowning_face — but I do find myself still relying on this profile in various projects, so I'd be happy to keep it updated. I've actually fixed a couple issues over the years that I've discovered with the profile (including this issue and some other needed refinements to range pagination). I'd be happy to submit those fixes back to the JSON:API repo before this profile is officially marked as "stable", if you'd like.

Pushing your fixes upstream sounds great. The status of the profile is currently somehow unclear. See #1527

But I think regardless if it is considered an official profile or community profile, I think it makes sense to improve it. Happy to review merge requests related to it.

To @jelhan's specific question, though, my intention was to specify option (1). That seems more useful to me -- otherwise, the truncated data would be totally inaccessible, right? -- but, if I'm missing something and (2) would be better for some reason, I'm very open to hearing the use case.

I think it would be still accessible. But the next page may not be within the original range anymore.

Thinking more about it, I'm wondering if selecting a range using pagination is actually a correct pattern. It seems to overlap more with filtering than with pagination:

• There are no meaningful next or previous pages for ranges. Meaningful pagination can only happen within a range. Otherwise pagination would only mean ignoring a given range for next and previous pages.
• There could be meaningful pagination within a range. As discussed in regard to truncated data in the profile itself.
• Range filters are very common. For date selection (e.g. "last year"), to define a minimum and maximum value (e.g. price range) and many more.

I would tend towards dropping support for using both page[before] and page[after] in the same request. Instead consumers should be pointed to filters for that use case.