How to implement API pagination

· Category: API & REST

Short answer

Pagination breaks large result sets into manageable chunks, improving response times and reducing client and server resource consumption.

Steps

  1. Offset pagination uses limit and offset query parameters but suffers from drift during concurrent modifications.
  2. Cursor pagination returns an opaque pointer to the next page, ensuring consistency.
  3. Keyset pagination filters on indexed columns such as created_at for stable ordering.
  4. Include total count or a has-more flag so clients know when to stop requesting.
  5. Set a maximum page size to prevent abuse and timeouts.

Tips

  • Prefer cursor or keyset pagination for high-write environments.
  • Return pagination metadata in response headers or a wrapper envelope.
  • Index sort columns to avoid full table scans during pagination.
  • Avoid offset-based pagination on large tables due to degrading performance.

Common issues

  • Inconsistent item ordering when no explicit sort is specified.
  • Duplicate or missing items when data changes between page requests.
  • Clients requesting extremely large page sizes causing memory pressure.
  • Lack of total count making it impossible to show progress bars.

Example

curl -X GET https://api.example.com/users   -H "Accept: application/json"   -H "Authorization: Bearer $TOKEN"

This curl command demonstrates a standard GET request with headers for content negotiation and bearer token authentication.