Pagination

[mnot]

I'd be curious to know if folks thought standards or guidance around pagination in APIs would be useful. We have RFC5005 but that's specific to Atom.

If so, what should we say?

[asbjornu]

Well, there are already numerous standard and non-standard solutions to this problem, so we could perhaps start with collecting what exists and figure out where to go from there? Here's a few from the top of my head:

• OData has $top and $skip.
• JSON:API has first, last, prev and next and is agnostic to the concrete paging strategy, but defines a Cursor Pagination Profile.
• GrahpQL has various different pagination alternatives.

…etc.

[darrelmiller]

I think having a standardized way of providing next links in a header for the purpose of pagination would be good. There are too many folks who have invented their own syntax for embedding into payloads.

I would love to suggest people to use Link Headers, but the syntax usually scares people away. Have there been thoughts around using structured headers as an alternative serialization for link headers?

[jameysharp]

If we're listing existing solutions, RFC5988's definition of first/prev/next/last in the context of the Link header should certainly be on the list, but so should the comments in RFC5005 section 3 about when that model isn't appropriate.

I'd love to see more systems match the functionality of RFC5005's section 4, allowing a client to be certain it hasn't missed a change in the paginated list when traversal races with updates. Dealing with concurrency is tricky as always and I haven't seen other pagination specs address that. Providing guidance might help.