APIs
APIs: contract and response reading
Crux Read real API contracts, responses, a pagination query, and rate-limit headers, then pick the senior call — the highest-leverage fix or the correct interpretation.
Your altitude — climbing toward senior
ZeroJuniorMiddleSenior
You are at senior altitude — in orbitAPI problems are diagnosed in the contract and on the wire: a route table, a response, a SQL page query, a set of response headers. Read each one and choose the call a senior would make first.
Goal
Practise the review loop you run on every public API: read the contract or the response, predict where it breaks under load or retry, and reach for the structural fix before reaching for a workaround.
Snippet 1 — the route table
POST /chargeCard
POST /refundCharge?id=123
GET /getUserOrders?user=42
POST /orders/{id}/cancel?action=cancel Quiz
Completed
This route table mixes several modeling mistakes. What is the single highest-leverage correction, and why does it matter most?
Heads-up Fixing ?id=123 to a path segment is half the job, but POST /chargeCard and ?action=cancel are still verbs. The core defect is verb-shaped resources, which is what poisons the status codes.
Heads-up Versioning is orthogonal; /v1/chargeCard is still a verb with the same retry problem. Versioning organizes evolution, it does not fix bad modeling.
Heads-up Creating a charge or cancellation mutates state — GET must be safe and idempotent. Making writes GET-able is a correctness and caching disaster.
Snippet 2 — the create-payment response
POST /payments
Idempotency-Key: 8f1c-...-a9
--> HTTP/1.1 200 OK
{ "status": "ok", "error": null } Quiz
Completed
The client sent an Idempotency-Key and the server returned 200 with no resource id. A timeout-driven retry follows. What is wrong and what should the server return?
Heads-up For a creation, 201 + Location is the honest code. A bare 200 with no id cannot tell a fresh create from an idempotent replay, which is exactly the ambiguity that drives double-charges.
Heads-up 204 means 'success, no body' — but a created payment must return its id/Location so the client can reference it and confirm the idempotent replay. 204 throws away the information the retry needs.
Heads-up 409 is for a conflicting state (e.g. a replay that collided with a different in-flight result), not for a successful first creation. The first write is 201; the safe replay is 200 with the original result.
Snippet 3 — the deep-page query
-- page 5001 of a live, growing feed
SELECT id, created_at, title
FROM posts
ORDER BY created_at DESC
OFFSET 100000 LIMIT 20; Quiz
Completed
This query backs a live, growing feed and deep pages are slow and occasionally drop or duplicate posts. What is the cursor-based rewrite and what does it buy?
Heads-up The index speeds the ORDER BY but OFFSET 100000 still scans and discards 100k rows every deep page. Keyset is what removes the discard, not the index.
Heads-up created_at is not unique — ties at the same timestamp get skipped or duplicated at page boundaries. A keyset cursor needs a unique tiebreaker (id), hence the composite (created_at, id).
Heads-up The feed is sorted by created_at DESC; paginating by id alone returns the wrong order. The cursor must match the sort key, with id only as the tiebreaker.
Snippet 4 — the rate-limit headers
HTTP/1.1 429 Too Many Requests
Retry-After: 8
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1716998400 Quiz
Completed
A client got this response. What is the correct client behavior, and what does each signal mean?
Heads-up Remaining is 0 and Retry-After is 8 — an immediate retry is guaranteed to be throttled again and amplifies load. The whole point of Retry-After is to make the client wait the stated window.
Heads-up 429 is a backoff signal, not a hard failure — the request is valid, just over quota. The client should wait and retry, surfacing an error to the user only if it persists past the reset.
Heads-up Retry-After and the X-RateLimit-* fields are exactly the documented quota signal; ignoring them turns a cooperative throttle into guesswork and can keep the client locked out longer.
Recap
Every API review reads the same artifacts: a route table tells you whether resources are nouns (and therefore whether status codes can be honest); a create response should be 201 + Location on first write and 200 on an idempotent replay, never a bare 200 with no id; a deep-page query should be a keyset cursor on a unique composite sort key, not OFFSET; and a 429 with Retry-After + X-RateLimit-* is a cooperative backoff contract the client must honor. Read the contract, predict the failure under retry or load, then apply the structural fix.