Pagination (API)
API pagination is the practice of returning large datasets in discrete pages rather than a single response, reducing server memory usage, response latency, and client processing burden; With cursor-based pagination, the server returns a next_cursor token alongside a page of results; Choosing the wrong pagination strategy creates subtle data integrity bugs
API pagination is the practice of returning large datasets in discrete pages rather than a single response, reducing server memory usage, response latency, and client processing burden. Common pagination strategies include offset/limit, cursor-based, and keyset pagination.
How it works
With cursor-based pagination, the server returns a next_cursor token alongside a page of results. The client passes this cursor in the next request, and the server uses it to efficiently locate the next page in the dataset without scanning from the beginning. Offset pagination uses numeric page and limit parameters but can produce inconsistent results on frequently updated datasets.
Key facts
- Cursor-based: More stable than offset for real-time datasets; cursor encodes the last seen record position
- Offset pagination: Simple but can skip or duplicate records if the dataset changes between pages
- Link header: RFC 5988 defines a standard Link header for expressing next, prev, first, and last page URLs
For builders
Choosing the wrong pagination strategy creates subtle data integrity bugs. For append-only logs, cursor-based pagination is reliable. For user-facing UIs with random access, offset pagination with stable sort order is acceptable.
Sources
- IETF. RFC 9110: HTTP Semantics. datatracker.ietf.org
- IETF. RFC 9112: HTTP/1.1. datatracker.ietf.org
- Fielding, R. (2000). Architectural Styles and the Design of Network-based Software Architectures (REST). UC Irvine. ics.uci.edu
- OWASP. API Security Top 10 (2023). owasp.org
- MDN Web Docs. HTTP reference. developer.mozilla.org
