Back to the Catalog
http
system-design

Designing an HTTP API (REST, Done Right)

14 questions

Most "REST" APIs are RPC in disguise. This quiz sharpens the decisions that matter when other people build against your endpoints: method safety and idempotency, PUT/PATCH/POST, idempotency keys, cursor vs. offset pagination, the real meaning of 409/412/422/429, versioning, and error envelopes a client can program against. Every answer is grounded in the HTTP specs (RFC 9110, RFC 5789, RFC 9457).

Start

Questions

  1. Not answered. Which of these HTTP methods are idempotent?
  2. Not answered. What does it mean for an HTTP method to be "safe"?
  3. Not answered. Update only a user's email, leaving every other field untouched. Which method fits best?
  4. Not answered. Why is PATCH not guaranteed to be idempotent, while PUT is?
  5. Not answered. A POST /charges times out before the response arrives; the client retries. How do you prevent a double charge?
  6. Not answered. An infinite-scroll feed over a constantly-growing table: a user must never see a duplicate or skip an item, and page 10,000 must be as fast as page 1. Which pagination design fits?
  7. Not answered. Which of these are genuine drawbacks of OFFSET/LIMIT pagination that keyset pagination avoids?
  8. Not answered. Your API does optimistic concurrency with a version field in the request body. A client sends version: 3, but the stored resource is already at version: 5 — someone updated it first. No If-Match header was sent. Which status code?
  9. Not answered. A client does a conditional update with If-Match: "v5" to avoid lost updates, but the resource's current ETag is "v7". Per RFC 9110, what 3-digit status code must the server return?
  10. Not answered. A client POSTs well-formed JSON to create a user, but email is "not-an-email" and fails validation. The body parsed fine. Which status code is most precise?
  11. Not answered. A client exceeds its rate limit. What's the correct status code, and which header should tell it when to try again?
  12. Not answered. Which response change is backward-compatible — safe to ship to existing clients without cutting a new API version?
  13. Not answered. Per RFC 9457 (Problem Details for HTTP APIs), what media type does a server put on Content-Type for a JSON error document?
  14. Not answered. An API returns HTTP 200 for everything and signals failure with { "ok": false } in the body. What's the core problem?