practiceEngineering & architecture

Pagination

The division of a large ordered result set into bounded portions that clients retrieve incrementally.

Download Markdown (.md)

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]

Collection traversal models Offset and cursor pagination make different stability tradeoffs
  1. 01Page numberHuman-friendly random access
  2. 02OffsetSimple position by count
  3. 03CursorOpaque continuation token
  4. 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

  1. Define a deterministic ordering and maximum page size.
  2. Choose offset, page number, cursor, or keyset semantics based on data change and navigation needs.
  3. Return the requested slice plus an opaque continuation link or documented page metadata.
  4. Preserve filters and authorization consistently while traversing pages.
  5. Handle deleted, inserted, expired, or inaccessible items without assuming a fixed total.
  6. Measure page latency, depth, abandonment, and expensive traversal patterns.

05A practical example

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

  1. Using Pagination in the REST APIGitHub Docs · Official technical documentationUsing Pagination in the REST API
  2. AIP-158: PaginationGoogle · Official API guidanceAIP-158: Pagination
View saved topics

Start typing to search titles, definitions, categories, and frameworks.