REST API Pagination Design

Pagination divides a large collection into bounded responses and tells the client how to continue. The first design decision is the order, not whether the parameter is named page or cursor. Without a stable order, page boundaries have no reliable meaning. If several orders share createdAt, add a unique tie-breaker such as id, for example ORDER BY created_at DESC, id DESC.

Offset pagination uses a distance such as /orders?offset=40&limit=20 or a page number translated to that distance. It is easy to understand and supports a direct jump to a later page, so it works well for smaller or mostly stable admin lists. Large offsets may be expensive, and inserts or deletes before the current position can shift the boundary between two requests.

Cursor pagination returns a server-issued token for the next position. With newest-first ordering, the token can represent the last (createdAt, id) pair, allowing the next query to continue after it rather than recounting from the front. This is usually steadier for a high-write feed. It does not naturally jump to page 37, and changes to a row's sort values can still affect what a client sees.

A page response should contain the items, the applied limit, and a next link or opaque cursor when more results may exist. The cursor must be used with the same collection, filters, and ordering that created it; the server should reject a mismatch. Page size needs a documented default and maximum. The server may return fewer items than requested, so item count alone should not be the end-of-list signal.

Offset is a good fit when page numbers and random jumps matter more than changes between requests. Cursor pagination is usually a better fit for a large, frequently updated stream. Neither design creates a frozen snapshot automatically, and an exact total can be slow or become stale while the client pages. The API should document ordering, continuation, expiry, total-count behavior, and what concurrent changes can do.