Pagination

Pagination divides a result list into separately retrievable pages. An API therefore does not have to send every record in one response. Page size, ordering, continuation and the way clients recognise the end of the list belong in the interface contract.

In a fictional example, a list sorted by identifier initially contains A, B, C, D. The first page returns A and B. Before the next request, AA is inserted between those entries. If an offset-based method now skips the first two current records, the next page starts at B again: one record appears twice. A unique ordering does not by itself freeze the data set.

Continuation needs explicit rules

A cursor can identify a continuation position, such as the position after the last returned record. Its exact meaning is defined by the API. A cursor does not automatically guarantee an unchanged snapshot; deletions and changes to sort values also need consideration.

In Google's token-based guidance, the continuation value is passed back unchanged rather than decoded by the client. Filters and other selection arguments stay the same; this contract allows the page size to change. The token does not replace an access check. A short or empty page does not establish the end of the list under this contract either: the absence of a continuation token does. Implement clients according to the documented contract of the API in use.

Sources

• Google — AIP-158: Pagination