API Pagination Strategy
API pagination strategy chooses between offset, cursor, and keyset pagination so the client can iterate a large collection without skipping or duplicating rows as the collection changes under it.
Definition
API pagination strategy is the design choice of how a client iterates a large collection — offset (skip N, take M), cursor (opaque pointer to the next page), or keyset (where column > last value) — so that the iteration is stable under concurrent inserts and deletes, performant at deep pages, and cacheable.
Context and scope
Applied in list endpoints, export APIs, and any collection whose size exceeds a single response and whose iteration must be correct under concurrent modification.
Common misconceptions
- Offset pagination is always fine — it is fine for small, stable collections; for large or changing collections it skips and duplicates and gets slow at deep pages
- Cursor pagination is opaque so it is not cacheable — the cursor encodes the position; the URL with the cursor is cacheable, the cursor itself is the cache key
Anti-patterns
- Using offset pagination on a collection that changes during iteration, so rows are skipped or duplicated
- Using a cursor that exposes the internal ID, so the client depends on the ID format and the cursor is not stable across a rekey
Related concepts
Authoritative source
https://use-the-index-luke.com/sql/partial-results/page-numbers
What it is
API pagination strategy is the design choice of how a client iterates a large collection — offset (skip N, take M), cursor (opaque pointer to the next page), or keyset (where column > last value) — so that the iteration is stable under concurrent inserts and deletes, performant at deep pages, and cacheable. Applied in list endpoints, export APIs, and any collection whose size exceeds a single response and whose iteration must be correct under concurrent modification. An API is a contract, and a contract’s value is the stability that lets clients and servers evolve independently — breaking the contract breaks the clients you do not control.
How it works
Versioning makes change explicit: a new field is additive, a removed or retyped field is breaking, and the client must be able to ignore what it does not understand. Pagination, filtering, and error formats are part of the contract, not afterthoughts. Documentation is generated from the schema so it cannot drift. Deprecation gives clients a runway, marked in headers and logs, before the removal.
When to apply and pitfalls
Apply whenever more than one client consumes the interface. The pitfall is treating the API as the implementation’s reflection — changing the URL because the internal class changed, exposing database columns as fields. Another is versioning by URL path and accumulating N parallel codebases rather than versioning by capability and evolving one.