chapter twenty one
21 Pagination
In this section, we’ll explore a pattern for consuming data when the number of data points (or the size of the data point itself) becomes too large for a single network request. This functionality is commonly seen in many web-interfaces and is equally important for APIs.
- APIs should support pagination, particularly if responses can be large.
- Consumers may supply a page size along with a continuation token on requests that support pagination.
- An empty continuation token in a response must indicate there are no more results (and a non-empty continuation token must indicate that there may be more results).
- Page sizes should be considered to be maximum (not exact) limits.
- Page sizes must be optional and should use a default value of 10.
- Page tokens must be obfuscated (completely opaque to consumers) or use a documented format (to be shared with consumers).
Page tokens may operate on either a snapshot of the data or the live data.