Pagination
Pagination is the API pattern for splitting a large collection into smaller pages so clients fetch results incrementally. It is one of the universal API design decisions, with consequences for performance, consistency, and the client developer experience.
Common strategies
- Offset / page-number.
?page=3&limit=20. Simple, supports jumping to arbitrary pages, but slow on large tables and unstable under concurrent inserts (a row added during paging causes duplicates or skips). - Cursor / keyset.
?cursor=eyJ.... The server returns an opaque cursor identifying the last item on the page; the client passes it back to fetch the next page. Stable under inserts, scales to any table size, but does not support arbitrary jumps. - Seek / row-value.
?after_id=5000. Like cursor, but using a visible field. Simpler, leaks ordering choice. - Time-based.
?since=2026-01-01T00:00:00Z. Common for activity feeds and audit logs.
Headers and metadata
APIs typically return paging metadata either inline ({ data: [...], next_cursor: "..." }) or in HTTP headers (Link: <...>; rel="next", following RFC 5988). Both work; pick one and stay consistent.
🔗