Pagination
The division of a large ordered result set into bounded portions that clients retrieve incrementally.
Download Markdown (.md)Soroush’s Product Wiki · https://wiki.soroush.uk/topic/pagination/
01What it means
Pagination is the API and interface practice of returning a limited portion of a collection together with information for requesting another portion. Page-and-offset models identify positions numerically; cursor or keyset models continue from a stable item boundary. Pagination controls transfer and processing, while the interface pattern determines how users navigate or load results.[1][2]
- 01Page numberHuman-friendly random access
- 02OffsetSimple position by count
- 03CursorOpaque continuation token
- 04KeysetContinue after stable values
Both require deterministic ordering, bounded page size, consistent authorization, and clear continuation semantics.
02Why it matters
Unbounded lists increase response time, memory, bandwidth, rendering work, and failure risk. A clear pagination contract keeps costs predictable and helps products provide usable navigation, but unstable ordering can cause users to miss or repeat items as data changes.
03When to use it
Paginate collections that can exceed a safely bounded response. Offset pages suit modest, relatively stable lists and direct page navigation; cursors suit large or rapidly changing feeds. A small capped collection or targeted search may not need pagination.
04How it works
- Define a deterministic ordering and maximum page size.
- Choose offset, page number, cursor, or keyset semantics based on data change and navigation needs.
- Return the requested slice plus an opaque continuation link or documented page metadata.
- Preserve filters and authorization consistently while traversing pages.
- Handle deleted, inserted, expired, or inaccessible items without assuming a fixed total.
- Measure page latency, depth, abandonment, and expensive traversal patterns.
05A practical example
An audit log orders events by timestamp and unique ID and returns an opaque next cursor. New events do not shift the continuation point, so an administrator can traverse older records without the duplicates produced by changing numeric offsets.
06Where it breaks
Offset pagination becomes slow or inconsistent on large changing datasets. Cursor pagination complicates direct page jumps, caching, and backward navigation, and cursors may expire. Exact total counts can be expensive or misleading under concurrent updates.
Common mistakes
- Paginating without a deterministic order and unique tie-breaker.
- Exposing database offsets or identifiers as if they were a stable long-term contract.
- Returning an expensive exact total on every request when the product does not need it.
- Allowing unbounded page sizes that defeat the protection pagination provides.
07Sources
- Using Pagination in the REST APIGitHub Docs · Official technical documentationUsing Pagination in the REST API
- AIP-158: PaginationGoogle · Official API guidanceAIP-158: Pagination