REST endpoints that return a paginated list of items should use a common schema for the envelope that facilitates the pagination.
The general shape of the envelope should look like this:
{
"items": [ ... ],
"pagination": {
"next": { ... }
}
}There should be a shared schema describing the envelope. Individual endpoints will then fill in the schema for elements of the "items" array using JSON schema's allOf mechanism. TBD: are items required to be objects for all endpoints?
The "next" entry in the "pagination" stanza is required, it will be null if there is no next page. We may add additional keys next to "next" in the future (required or optional is TBD): "first" would be easy, for endpoints that support inverse sorting we could also have "previous", "last", and "reverse". Implementing "previous" without the need to reverse the sort order is tricky - the pagination direction would dictate the database sort order, items may be re-sorted for output.
The biggest open question is the exact shape of the cursor used by "next" and friends. Options:
- a JSON object of query parameters (to be merged with other parameters by the client). This is what the Action API already uses.
- an opaque Base64 cursor, containing an encoded JSON object of query parameters (to be merged with other parameters by the server). This is the industry standard.
- a full href pointing to the next page. This follows the linked-data paradigm but may not work well with how clients are typically implemented (with a configurable base URL).
Notes:
- All three would map to an array of query parameters internally, and would be compatible with how the Action API currently implements pagination.
- The options are not mutually exclusive: the envelope could carry more than one. Adding a mechanism later is easy. Removing one is not, so each extra field is a long-term commitment.
- The same envelope is meant to be shared by native REST endpoints, Action-API-over-REST list routes and perhaps even a future GraphQL endpoint.
- Cursors are not stable for unstable rankings (e.g. offset-based generator=search) and can drift or repeat across pages.
- Pagination has to be based on a unique key; if that key is based on a mutable property, items may be skipped or duplicated: if Zack is renamed to Aaron while the client is looking at the page from Francis to Mandy, they will never see the entry for Zack or Aaron.