- API design
- developer guide
- pagination
- web engineering
API Pagination: Cursors, Offsets and Reliable Continuation
, by System Admin
Pagination lets an API return a large collection in manageable responses instead of making clients transfer and process everything at once. A good design also makes it clear how clients continue, what happens as data changes, and when the collection is finished.
Choose a continuation model
Offset pagination uses a position such as ?limit=50&offset=100. It is easy to understand and can work well for small, relatively stable collections or interfaces that need to jump to a numbered page. But large offsets may become expensive, and inserts or deletes before the current offset can cause clients to miss or see records twice between requests.
Cursor pagination returns an opaque continuation token that the client sends back to fetch the next page. The server can use a record position rather than counting through every earlier row. Cursor pagination is often a better fit for large or frequently changing feeds, but it usually does not support jumping directly to an arbitrary page.
Neither approach is universally right. Choose based on the collection’s size, change rate, query cost, and the navigation your clients actually need.
Define a stable order
Pagination needs deterministic ordering. Sorting only by a field that can be shared by many records—such as a timestamp—can leave ties in an unpredictable order. Add a unique tie-breaker, often the record ID, so each item has a consistent position. For cursor pagination, the cursor must contain or reference every sort value needed to continue from that position.
Decide what clients should expect if records change while they paginate. Some APIs provide a consistent snapshot; others expose the live collection, where additions and removals may affect later pages. Document the chosen behaviour rather than implying a snapshot that the service does not provide.
Make the token safe and predictable
Use a bounded, optional page-size parameter with a documented default and maximum. Clamp requests above the maximum instead of letting one client demand an unbounded response. Returning fewer results than requested can be valid—for example, when the service has a response-size or query-time limit—so clients should follow the continuation token rather than assuming a short page means the end.
Keep continuation tokens opaque and URL-safe. Do not make clients construct or interpret them, and do not treat possession of a token as authorization: authenticate and authorize every page request normally. If a token embeds sensitive sort values or identifiers, protect those values rather than exposing them in readable form.
Make the end condition unambiguous
Return a next_page_token when another page may be available, and omit or leave it empty when the collection is complete—then document which convention your API uses. Clients should stop only when the response signals there is no next page, not merely because a page contains fewer items than requested.
Keep the filters and sort order unchanged while following a token. If the query changes, start a new pagination sequence. Consider a reasonable token expiry when tokens refer to stored server-side state, and return a clear client error if a token is invalid or expired.
Test the awkward cases
- An empty collection and a final page smaller than the requested size.
- Many records with identical sort values, plus inserts or deletes during traversal.
- Invalid, expired, or tampered tokens, and attempts to reuse a token with different filters.
- Zero, negative, and over-maximum page sizes.
- Large collections under realistic database load.
Google’s API Improvement Proposal on pagination recommends designing pagination into collection APIs from the outset, documenting page-size behaviour, using opaque page tokens, and signalling completion with an empty next-page token. Its guidance is a useful baseline; adapt the details to your API’s consistency and navigation requirements.