Course contentsShow
← Software Engineering
Lesson 785 of 1,93324. REST API DesignFree lesson

Cursor-Based Pagination

Using opaque cursors to paginate through ordered datasets reliably, avoiding page drift and handling deletions.

Cursor-Based Pagination

You'll learn how to paginate datasets using opaque cursors, avoiding the pitfalls of offset-based approaches.

What Is Cursor-Based Pagination?

In cursor-based pagination, instead of requesting "page 3" or "skip 50 items," the client receives an opaque cursor — a token pointing to a specific position in the dataset. To fetch the next batch, the client sends this cursor back, and the server resumes from exactly that position.

Think of it like a bookmark in a physical book. The bookmark doesn't say "page 42," it marks the exact spot where you stopped. Even if someone tears out earlier pages (deletions) or adds new chapters at the beginning (insertions), your bookmark still points to the right place.

Why Use Cursors?

Offset-based pagination suffers from page drift: if items are added or deleted while a user paginations through results, they might see duplicates or miss items entirely. Cursor-based pagination solves this by anchoring to the actual data, not arbitrary numeric offsets.

The cursor is typically a Base64-encoded value containing information like a timestamp, ID, or sort key that uniquely identifies the resumption point. Because it's opaque, clients can't manipulate it — they simply pass it along.

How It Works

  1. Client requests first page: GET /posts?limit=10
  2. Server returns 10 posts plus a next_cursor token
  3. Client requests next page: GET /posts?limit=10&cursor=abc123xyz
  4. Server decodes cursor, resumes from that exact position

This approach reliably handles deletions: if item #5 disappears, the cursor still knows where #6 begins.

Key Takeaway: Cursor-based pagination uses opaque tokens to mark exact positions in ordered datasets, eliminating page drift and handling data changes gracefully during pagination.