Offset pagination is easy to understand, but a changing dataset can shift rows between requests. A cursor can point to the last stable sort position and reduce duplicate or missing results during traversal.

Use a deterministic ordering

  • Sort by a field that is stable and unique, or add a unique tie-breaker such as an ID.
  • Encode the last seen sort values into an opaque cursor rather than accepting arbitrary database expressions.
  • Return a next cursor only when another page is available, and define what an empty result means.

Keep cursors scoped and bounded

Validate a cursor, bind it to the relevant filter and authorization context, and set a maximum page size. Treat it as navigation state rather than a secret or a permission grant.

Test insertions and deletions between requests, repeated cursors, and invalid cursor input. Cursor pagination improves traversal consistency, but it does not create a frozen snapshot unless the API explicitly provides one.