Keep pagination consistent when the dataset changes

An export can contain the expected number of rows and still miss an important record. While the client reads one page, another user inserts or removes data. Pagination therefore needs a consistency contract, not just a page-size setting and a button labeled next.

Decide what the result must represent

Ask whether the customer needs a live browsing view, a best-effort synchronization, or a fixed export. These are different products. A browsing list may tolerate movement. A reconciliation file may need a defined cutoff and an explanation of changes after that cutoff.

GitHub recommends a stable sort order when paging and notes that adding or removing entries can still shift items across pages.[6] This is a useful warning against assuming stable sorting alone creates a snapshot. Specify ordering, tie-breaking, and consistency independently so customers know what a completed traversal actually covers.

Choose continuation rules deliberately

For APIs you control, consider continuation based on the last ordered key rather than a numeric offset. Pair a nonunique sort field with a unique tie-breaker. Define how the next request treats a record whose sort value changes after an earlier page.

A cursor, meaning a continuation token, is not automatically a database snapshot. State whether it carries position, filters, snapshot identity, or some combination. Recommend opaque tokens with documented expiry and invalid-token behavior. For a fixed export, consider a server-created export job or snapshot mechanism. That choice adds storage or database cost and may delay availability.

Keep the user experience honest when a token expires. Offer a restart with its consistency implications, rather than silently switching the remaining pages to an unrelated view.

Check the entire traversal

When consuming a provider API, follow its documented continuation mechanism. GitHub specifically advises using its link headers instead of constructing pagination queries manually.[6] Keep filters consistent across requests and retain enough checkpoint information to restart safely without claiming unproven completeness.

• Define a total order with an explicit tie-breaker.
• Test insertion and deletion before and after the current position.
• Test updates to sort fields, empty pages, and expired tokens.
• Distinguish duplicate suppression from proof that no records were missed.

Hypothetical example: an inventory reconciliation

Hypothetical example: a retailer downloads inventory while staff continue updating stock. The team chooses an export job with a declared cutoff because the finance review needs a consistent baseline. Operational screens continue to show live data separately.

The export includes a job reference and a completion state. If a download stops, the client resumes that same export rather than restarting against a changing list. Keeping the export consumes storage and requires an expiry rule. Before selecting this design, ask the reviewer whether a fixed baseline is truly necessary or whether a clearly labeled live view would meet the decision need.