How to Paginate API Results: Best Practices

How to Paginate API Results: Best Practices

Pagination is essential for APIs that return large datasets. Without it, a single request can return thousands of records, causing slow responses, high memory usage, and poor user experience. This guide covers how to paginate API results using modern best practices, comparing offset and cursor-based approaches, and showing real-world implementation patterns.

Why Pagination Matters

A well-designed pagination strategy keeps APIs fast, predictable, and scalable.

Offset vs Cursor Pagination

The two dominant pagination patterns are offset-based and cursor-based. Each has distinct tradeoffs.

Rule of thumb: Use offset pagination for small, mostly static datasets. Use cursor pagination for large, frequently updated datasets or infinite scroll.

REST API Pagination Patterns

Offset Pagination with Limit

The simplest approach passes offset and limit query parameters.

GET /api/orders?offset=40&limit=20

Pros: Easy to implement, familiar to clients, supports random page access. Cons: Database must scan and discard skipped rows, rows can shift between requests.

Cursor Pagination with bookmarks

Return a next_cursor opaque token in the response. Clients send it back to fetch the next page.

GET /api/feed?cursor=eyJpZCI6MTIzfQ&limit=20

Pros: Constant query cost, no duplicates or misses, ideal for real-time feeds. Cons: No random page access, cursor usually encodes internal state.

Keyset Pagination

Use explicit column values instead of an opaque cursor.

GET /api/orders?last_id=1024&limit=20

Pros: Transparent, cacheable, index-friendly. Cons: Requires a stable unique ordering column.

GraphQL Pagination Patterns

Relay-Style Cursor Connections

GraphQL community standards recommend Relay-style cursor connections.

query {
  products(first: 20, after: "opaqueCursor") {
    edges { node { id name } cursor }
    pageInfo { endCursor hasNextPage }
  }
}

This pattern bundles edges, cursors, and navigation metadata into a single response.

Offset-Based in GraphQL

Simpler but less common in production GraphQL APIs.

query {
  users(offset: 40, limit: 20) {
    id name
  }
}

Modern Best Practices for Pagination

Response Envelope Example

A modern response envelope gives clients everything they need to navigate.

{
  "data": [...],
  "pagination": {
    "limit": 20,
    "offset": 40,
    "total": 542,
    "next_cursor": "eyJpZCI6NDB9",
    "prev_cursor": "eyJpZCI6MjB9"
  }
}

For cursor pagination, omit total if counting is expensive, and rely on hasNextPage.

Database Query Patterns

Efficient pagination requires the right query shape.

Add covering indexes on ordering columns. Avoid SELECT * in paginated endpoints; project only needed fields.

Infinite Scroll vs Pagination UI

Choose the right UX pattern for your product.

For SEO-critical content, traditional pagination with rel="next" and rel="prev" links ensures search engines discover all pages.

Common Pagination Mistakes

Conclusion

Effective pagination balances client experience, database performance, and API security. Start with cursor pagination for new APIs handling large or dynamic datasets. Add offset pagination only when random page access is a hard requirement. Always document limits, enforce maximum page sizes, and monitor query performance in production.