Idempotency, Pagination & API Versioning

Part 1: Idempotency

Why retries are unavoidable

Networks fail in a tricky way: the client often cannot tell whether the request succeeded. A retry means sending the same request again.

Retries happen everywhere: mobile apps, SDKs, load balancers, queues (lesson 18) and users tapping twice. So every operation that changes something should be safe to repeat.

Naturally idempotent vs not

• GET, PUT, DELETE are idempotent by design (lesson 3). "Set the name to Asha" twice gives the same result. "Delete order 7" twice leaves it deleted.
• POST usually is not. "Create a payment" twice creates two payments.
• Relative updates are not either. "Add ₹100 to the balance" twice adds ₹200.

Idempotency keys

The standard fix, made popular by Stripe, is an idempotency key. The client creates a unique key (such as a UUID, a random unique ID) for each logical operation, and sends it in a header. A logical operation is one real action, like one payment, even if it is sent many times. Retries reuse the same key.

POST /paymentsIdempotency-Key: 7f3c9a2e-4b1d-4e8a-9f0c-2d6b1e5a8c33Content-Type: application/json{"amount": 249900, "currency": "INR", "source": "card_123"}

The server's steps:

Idempotency table
┌──────────────────────────────┬──────────┬───────────────┬──────────────┬─────────────┐
│ key                          │ status   │ request_hash  │ response     │ expires_at  │
├──────────────────────────────┼──────────┼───────────────┼──────────────┼─────────────┤
│ 7f3c9a2e-4b1d-...            │ done     │ a91f...       │ {201, {...}} │ +24 hours   │
└──────────────────────────────┴──────────┴───────────────┴──────────────┴─────────────┘

Important details:

• A unique constraint on the key makes the "check then insert" step race-free (lesson 21). A race happens when two requests run at the same time and clash. Two simultaneous retries cannot both win.
• Store a hash of the request body. A hash is a short fingerprint of data. If the same key arrives with a different body, it is a client bug, so reject it (for example with 422).
• Scope keys per client or account, so different customers' keys cannot clash.
• Expire keys after a reasonable window (for example, 24 hours).
• Save the result in the same transaction as the work where possible. A transaction is a group of database changes that all succeed or all fail together. If the work involves an external system (a card network), pass the idempotency key downstream too.

Other idempotency techniques

• Natural unique keys: a unique constraint on (order_id) in the payments table means "one payment per order", however many retries arrive.
• Upserts: "update or insert" in one step, for example INSERT ... ON CONFLICT DO NOTHING / DO UPDATE (PostgreSQL).
• Conditional updates: UPDATE ... WHERE version = 7 or If-Match ETags (lesson 30).
• Deduplicating consumers: queue workers write down the IDs of messages they already handled, and skip repeats (Part 6).

Webhooks need it too

A webhook is a call that your server makes to another system's URL when something happens. When your API sends webhooks ("payment succeeded"), you retry on failure, so receivers may get the same event twice. Good webhook design:

• include a unique event ID so receivers can deduplicate,
• sign each payload with an HMAC signature (a code made with a shared secret key) so receivers can check it is really from you,
• retry with backoff (wait longer after each failure) for hours or days, and
• expect receivers to reply quickly and do heavy work later, in the background (asynchronously).

Part 2: Pagination

Never return a list with no limit. Always paginate, with a default page size (for example 20) and a maximum (for example 100).

Offset pagination

Offset pagination says "skip this many items, then give me the next few". limit is the page size, and offset is how many items to skip.

GET /orders?limit=20&offset=0      → orders 1–20GET /orders?limit=20&offset=20     → orders 21–40

SELECT * FROM orders ORDER BY created_at DESC LIMIT 20 OFFSET 40;

• ✅ Simple, and lets users jump to "page 7".
• ❌ Slow for deep pages. The database must read and throw away all the skipped rows. OFFSET 1000000 reads a million rows to return 20.
• ❌ Unstable when data changes. If a new order is inserted while you page, everything shifts by one, and you see an item twice. If one is deleted, you skip one.

Cursor (keyset) pagination

Cursor pagination (also called keyset pagination) uses a cursor. A cursor is a marker that points to the last item you received. Instead of "skip N rows", you say "give me the next 20 after this item":

GET /orders?limit=20→ { "data": [...], "has_more": true, "next_cursor": "eyJjcmVhdGVkX2F0Ijoi..." }GET /orders?limit=20&cursor=eyJjcmVhdGVkX2F0Ijoi...

Inside, the cursor holds the last item's sort values (for example created_at + id). The server turns them into a query like this:

SELECT * FROM ordersWHERE (created_at, id) < ('2027-01-20 10:15:00', 88231)   -- the last item seenORDER BY created_at DESC, id DESCLIMIT 20;

• ✅ Fast at any depth, because it uses an index (a sorted lookup structure) to jump straight to the position (lesson 22).
• ✅ Stable. Inserts and deletes do not cause duplicates or gaps.
• ❌ You cannot jump to an arbitrary "page 537". You can only go next and previous (fine for feeds and infinite scroll).
• Include a unique tie-breaker (like id) in the sort, so items with the same timestamp are not skipped. A tie-breaker is a second sort field that makes every position unique.
• Make cursors opaque (for example, base64-encoded JSON). Opaque means clients cannot read the inside. They should not parse or build cursors, so you can change the format later.

Response shape example:

{  "data": [ { "id": "ord_88231", "total": 129900 } ],  "has_more": true,  "next_cursor": "eyJjIjoiMjAyNy0wMS0yMFQxMDoxNTowMFoiLCJpIjo4ODIzMX0="}

Some APIs put next and previous links in an HTTP Link header instead.

Which to use:

• Offset: small datasets and admin tables that need page numbers.
• Cursor: feeds, timelines, large or frequently changing lists, and public APIs.

Avoid exact total counts on huge lists. COUNT(*) (count all rows) over millions of rows is slow. Show "has more", or an approximate count, instead.

Part 3: API versioning

A breaking change is a change that makes existing clients fail. Versioning lets you make such changes without hurting clients that still use the old form.

What counts as a breaking change?

Safe (non-breaking) changes:

• adding a new endpoint,
• adding a new optional request field,
• adding a new response field (clients should ignore fields they do not know. This is the "tolerant reader" rule),
• adding a new enum value, if clients are written to handle unknown values.

Breaking changes:

• removing or renaming a field or endpoint,
• changing a field's type or meaning (price in rupees → paise),
• making an optional field required,
• changing error codes or status codes clients rely on,
• changing default behaviour (sort order, page size).

The best strategy is to avoid breaking changes. Add new fields next to old ones and keep the old ones working. Remove them only after a long deprecation period. Deprecation means announcing that something will be removed later.

Ways to version

Date-based versions (popularised by Stripe) work like this:

• each account or client is pinned to the API version that existed when it started integrating,
• when a breaking change is released, it becomes a new dated version,
• clients upgrade when they choose,
• inside, the server uses small "version change" layers that translate between versions. Old versions keep working, and the code is not copied.

Deprecation done well

1. Announce early, with a clear timeline (for example, 6–12 months).
2. Mark it in responses. The Sunset HTTP header (RFC 8594) tells clients the date when an endpoint will stop working. A deprecation notice can point to the migration guide.
3. Monitor usage. See which clients still call the old version, and contact them directly.
4. Provide migration guides and, where possible, tools.
5. Only then switch it off. You can first run short "brownouts" (planned, temporary shutdowns) so that clients who missed the news notice.

Mobile apps make this harder

A web frontend updates as soon as you deploy it. But mobile apps stay installed for months or years, and many users never update. So:

• keep old API versions alive longer for mobile clients,
• have the app send its app version so the server can adapt,
• build a "minimum supported version" / force-update mechanism for breaking changes that cannot be avoided.