Glossary · 2 · Developer SDKs and APIs
Pagination (API)
Also known as: Pagination, Paging, API pagination
In API design, pagination is the division of a large result set into a sequence of smaller pages that a client requests one after another, using page numbers or offsets, opaque cursors (page tokens) or links to the next page supplied by the server.
- Developer SDKs
In one sentence
API pagination splits large result sets into pages requested one by one via offsets, cursors or next-page links; SDKs often iterate them.
Example
A list call returns 100 records and a next-page token; the SDK's iterator requests the following pages automatically until the token is empty.
How it applies
- Offset and page-number pagination: The client asks for items 201–300 or for page 3. It is simple to implement and to document, but results can shift between requests when items are added or deleted, and large offsets are slow on many databases.
- Cursor or token pagination: The server returns an opaque token that marks where the next page starts; the client passes it back unchanged. AIP-158 describes this pattern with
page_size,page_tokenandnext_page_tokenand requires that all other request parameters stay the same between pages. - Link-based pagination: The server sends the URLs of the next, previous, first or last page, for example in an HTTP
Linkheader with link relations as defined in RFC 8288; GitHub's REST API documents this approach. - Developer SDKs: Client libraries usually hide pagination behind an iterator or a “list all” helper that requests further pages on demand. Documentation should say whether such a helper loads lazily, how many requests it may send, how it interacts with rate limits and what happens when a page request fails halfway.
- Interface definition: Page size limits, default sizes, sort order and token lifetime are part of the interface contract and belong in the API reference.
Pagination vs. streaming
Pagination lets the client pull bounded pages in separate requests and stop at any point. Streaming delivers a sequence of items over one long-lived connection, as in server-streaming RPC. Pagination is easier to retry page by page; streaming avoids repeated round trips but needs a strategy for interrupted connections.