What is Pagination?
Also called Paging.
Pagination is the practice of returning a large result set in smaller sequential pages rather than all at once. The response carries one page of items plus a way to request the next, such as a page number, an offset, or an opaque cursor. It bounds memory, response size, and query cost for both sides.
The two dominant families are offset based and cursor based. Offset pagination asks for a limit and a starting position, which is simple and allows jumping to an arbitrary page, but grows slower as the offset increases because the database must still traverse the skipped rows. Cursor pagination passes an opaque marker for the last item seen and reads forward from it efficiently.
Offset pagination is also unstable under concurrent writes. If a record is inserted or deleted while a client walks the pages, items can be duplicated across pages or skipped entirely, because position is computed fresh on each request. Cursor pagination anchors to a specific record and a stable sort, so ongoing changes do not shift what has already been read.
Well designed paginated responses make the next step explicit rather than leaving clients to construct URLs. Returning a ready to use next link, or a null when the sequence ends, removes an entire class of client bugs. Total counts are sometimes omitted deliberately because computing an exact count over a large table can cost more than fetching the page.
Automated clients need guardrails. A loop that follows next links must cap iterations, honor rate limits between pages, and stop when the marker stops advancing, otherwise a bug on either side can turn one query into an unbounded crawl. Server side maximum page sizes exist for the same reason.
Key points
- Large results returned as sequential bounded pages
- Offset paging allows jumps but degrades and can skip items
- Cursor paging is stable under concurrent writes
- Return an explicit next link, null at the end
- Automated loops need iteration caps and rate limiting
In practice
A client requests the first fifty contacts and receives fifty records plus a next link. It follows that link repeatedly, pausing briefly between calls to stay inside the rate limit, until a response arrives with next set to null. A new contact created midway does not cause an earlier record to be returned twice, because the API pages by cursor rather than by numeric offset.