Design stable API pagination | DevPrompt Lab

A pagination design prompt that considers changing datasets, valid sort fields, and client navigation needs.

Reusable content

Design pagination for the collection endpoint. Define default and maximum page size, page-number or cursor semantics, deterministic tie-breaking, filter interaction, sort allowlist, and response metadata. Explain behavior for invalid or out-of-range values and empty results. Ensure user-provided sort values cannot enter SQL. Consider how inserts during navigation affect duplicates or omissions. Keep the contract consistent with existing clients and provide example requests and responses.

Collection: {{COLLECTION}}

Allowed sorts: {{SORT_OPTIONS}}

Client limits: {{CLIENT_LIMITS}}

How to use it

Prefer an explicit sort allowlist and stable unique secondary key in every ordering.

Example

Response: items, total, page, perPage, totalPages. Order by updated_at DESC, id ASC to make ties deterministic.