4.Bookmarks and New Editions

The Problem in Real Life

"Here's Everything, Forever Unchanged" vs. Pages, Questions and Versions

Pagination, Filtering, Sorting and API Versioning

• Pagination — one page at a time: the API returns a limited number of items per response (say 100) plus a way to get the next page. Responses stay small and fast, no matter how much data exists.
• Offset pagination — "page 3, please": GET /v1/orders?limit=100&offset=200 means "skip 200, give me the next 100". Simple and lets you jump to any page. But it gets slower deep into big tables (the database still has to count past the skipped rows), and if new orders arrive while you're paging, items can shift between pages — you might see one twice or miss one.
• Cursor pagination — a bookmark: instead of a page number, each response includes a cursor: a bookmark pointing to exactly where you stopped. GET /v1/orders?limit=100&after=ord_9F2a. It stays fast on huge tables and doesn't skip or repeat items when new data arrives. You can't jump to "page 37", but for "go through everything" — like a nightly sync — it's the better choice.
• Filtering — narrowing the search: query parameters let callers ask only for what they need: ?status=paid&createdAfter=2026-11-20T00:00:00Z. Less data, less work, fewer timeouts. (The server still validates every parameter — Act 22.)
• Sorting — choosing the order: ?sort=createdAt (oldest first) or ?sort=-createdAt (newest first — the minus means descending). Pagination needs a stable order, or pages can overlap.
• Versioning — new editions: a breaking change is anything that could break an existing caller: renaming or removing a field, changing a type, making an optional field required. Non-breaking changes — adding a new optional field or a new endpoint — are safe. For breaking changes, publish a new version (/v2/orders) and keep /v1 running for a while. Announce a deprecation date and give consumers time — often months — to move.

GET /v1/orders?status=paid&createdAfter=2026-11-20T00:00:00Z&sort=createdAt&limit=100

{
  "data": [
    { "orderId": "ord_1042", "status": "paid", "amt": 178.00, "totalAmount": 178.00, "createdAt": "2026-11-20T19:42:10Z" }
    // ... up to 100 orders
  ],
  "nextCursor": "ord_9F2a",     // pass as ?after=ord_9F2a for the next page
  "hasMore": true
}