Software API Pagination Checklist

Pagination is a data integrity concern as much as a performance concern. A client can miss or duplicate records when ordering, cursors, updates, retries, and limits are not defined together.

Choose a stable method

Document cursor, offset, page number, time window, or keyset pagination and explain which resources use it. Prefer a method that remains stable when records are added or changed during retrieval.

Define ordering and limits

Record sort fields, tie-breakers, maximum page size, default size, token expiration, and the meaning of an empty or final page. Validate client requests and prevent a large limit from degrading the service.

Handle changes during a scan

Explain snapshot, cursor, or eventual-consistency behavior when records are created, deleted, or updated while a client is paging. Preserve stable identifiers and make duplicates or gaps detectable.

The API security checklist and API versioning checklist help connect data behavior to the public contract.

Design retries and rate limits

Make requests safe to retry, honor provider limits, preserve the cursor, and avoid restarting a long scan after a transient error. Record the last successful page and a recovery path for background jobs.

Test boundaries

Test zero, one, exact page size, large result sets, duplicates, deleted records, expired cursors, invalid tokens, changed ordering, permissions, rate limits, and provider failures.

Monitor completeness

Track pages, records, latency, retries, empty pages, cursor failures, duplicates, gaps, rate-limit responses, and job age. Reconcile sample totals with the source when the data supports an independent check.