Pagination: Cursor vs. Offset
You'll learn to
- -Explain pagination as handing back a large list in small, predictable pages
- -Watch offset pagination show a post twice when a new one arrives, and cursor pagination avoid it
- -Build a response envelope that says whether more pages exist, with an opaque cursor
Tip: the highlighter is on - just select any text below to mark it. Use the highlighter button up top to change color or turn it off. Highlights are saved on this device only. Log in to save them to your account instead.
No collection endpoint should return "everything" unbounded. Pagination caps the size of each response and gives clients a predictable way to walk through a large result, a page at a time. The two common approaches, offset and cursor, look similar and behave very differently once new data keeps arriving.
An Analogy: A Bookmark vs. a Page Number
Reading a long, growing list is like reading a stack of papers where new sheets keep being added on top. If you remember "I was on the fourth sheet" (an offset), then a new sheet on top pushes everything down and you read one sheet twice. If you put a bookmark on the exact sheet you finished (a cursor), new sheets on top do not matter, and you continue from your bookmark.
Offset Pagination: Simple, With a Real Bug
GET /orders?limit=20&offset=0 # first 20 orders
GET /orders?limit=20&offset=20 # next 20 ordersOffset pagination is trivial to build and lets a client jump straight to "page 5". But if a row is inserted before the current position while the client is paging, every later page shifts by one. The client then skips an item or sees one twice. On a slow-changing admin table that rarely matters. On a live feed with constant writes, it is a visible bug.
Cursor Pagination: Stable When Data Changes
GET /orders?limit=20
HTTP/1.1 200 OK
{
"data": [ /* 20 orders */ ],
"next_cursor": "eyJpZCI6MTIwfQ==",
"has_more": true
}
# the client passes the returned cursor to get the next page:
GET /orders?limit=20&cursor=eyJpZCI6MTIwfQ==A cursor encodes a stable position, usually the last item's sort key such as its id or timestamp, and is often base64-encoded so clients treat it as an opaque token. The next page is defined as "after this item", not "skip N rows", so an insertion elsewhere does not shift what comes next. The trade-off is that a client can no longer jump to page 5 without walking the pages before it.
The demo shows both side by side. A client reads page 1 of ten posts three at a time, then a new post arrives, and the client asks for page 2 each way.
The Response Envelope
Whichever approach you use, the response should say explicitly whether more data exists, with has_more or a next_cursor that is simply null on the last page. Do not make the client guess from getting fewer than limit items back. That guess fails when the total happens to land exactly on a page boundary.
Do not hand out a raw internal id as a "cursor". A token the client can trivially decode and edit is not opaque, and clients will inevitably start relying on its internal structure once they notice it.
You're designing pagination for a social media feed that receives new posts constantly. The interviewer asks why you'd avoid offset pagination here specifically.
"Offset pagination is generally worse, so I'd always avoid it."
"For a feed with constant writes, offset pagination has a real correctness bug: if new posts are inserted while a user scrolls, every post shifts position in the underlying order, so the client can end up seeing the same post twice or skipping one entirely between page loads. Cursor pagination avoids this because each page is defined relative to 'after this specific post,' which stays correct regardless of what gets inserted elsewhere. I wouldn't rule out offset pagination everywhere, though - for a rarely-changing admin table where jump-to-page matters more than write-concurrency correctness, it's still a reasonable choice."
What correctness problem does offset pagination have under concurrent writes?
Design Page Turner in the API Design Lab's REST Foundations act.
Discussion0
Join the Discussion
Sign in to leave comments, reply to others, or like insights.
No comments yet. Be the first to start the thread!