API Pagination Best Practices

Best Practice: API Pagination Best Practices

Pagination returns large collections in bounded chunks so a single request never fetches an entire dataset. The two main strategies are offset pagination (skip N, take M) and cursor or keyset pagination (return items after an opaque cursor). Offset is simple but degrades on large tables and produces duplicates or gaps when items are inserted or deleted mid-traversal. Cursor pagination is stable and performant because it seeks by a sorted key rather than counting rows. Google's API Improvement Proposals recommend opaque page tokens. Pagination matters because unbounded responses harm latency, memory, and reliability for both server and client.

Step-by-Step Implementation Guidance

1. Default to cursor (keyset) pagination for large or frequently changing collections.
2. Define a stable total ordering (for example created_at plus a tiebreaker id).
3. Return an opaque next-page token that encodes the position; never expose raw offsets clients can tamper with.
4. Set and enforce a maximum page size; apply a sensible default when the client omits it.
5. Indicate when more results exist (a next token present or a has_more flag).
6. Keep the contract consistent across endpoints so clients reuse pagination logic.
7. Avoid returning a total count on huge tables; compute it lazily only when cheap.

Common Mistakes Teams Make When Ignoring This Practice

• Returning entire collections, exhausting memory and timing out.
• Using offset pagination on large tables, causing slow deep pages.
• Producing duplicate or skipped rows when data changes during traversal.
• Allowing unbounded page sizes that let one request fetch millions of rows.
• Inconsistent pagination shapes across endpoints, forcing bespoke client code.

Tools and Techniques That Support This Practice

• Keyset pagination with indexed sort columns in SQL.
• Relay-style connections (edges, cursors) in GraphQL.
• Database indexes aligned to the pagination order.
• API style guides (Google AIP-158) for consistent page-token semantics.

How This Practice Applies to Different Migration Types

• Cloud Migration: Bounded pages keep request sizes predictable across higher-latency network hops.
• Database Migration: Cursor pagination lets bulk export and backfill jobs traverse tables safely while writes continue.
• SaaS Migration: Consuming a provider's paginated API requires following its cursor contract to extract all data.
• Codebase Migration: Standardizing pagination during a rewrite removes inconsistent legacy paging logic.

Checklist

• Cursor/keyset pagination used for large collections.
• Stable total ordering with a tiebreaker defined.
• Opaque next-page tokens returned.
• Maximum and default page sizes enforced.
• Presence of more results signaled clearly.
• Pagination contract consistent across endpoints.
• Expensive total counts avoided or made optional.