Back to the catalog
httpsystem-design

HTTP API design: methods, status codes, pagination, and errors

14 questions

Many APIs called REST are really RPC over HTTP. This quiz covers the choices that matter once other developers build against your endpoints: safe and idempotent methods, PUT vs. PATCH vs. POST, idempotency keys, cursor vs. offset pagination, what 409, 412, 422, and 429 mean, versioning, and error formats a client can parse. Most answers point to the relevant spec (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. You want to change a user's email and leave every other field alone. Which method fits best?
  4. Not answered. Why is PATCH not guaranteed to be idempotent, while PUT is?
  5. Not answered. A POST /charges request times out before the response arrives, and the client retries. How do you prevent a double charge?
  6. Not answered. An infinite-scroll feed reads from a table that keeps growing. Users must never see a duplicate or miss an item, and page 10,000 must load as fast as page 1. Which pagination design fits?
  7. Not answered. Which of these are real drawbacks of OFFSET/LIMIT pagination that keyset pagination avoids?
  8. Not answered. Your API handles optimistic concurrency with a version field in the request body. A client sends version: 3, but the stored resource is already at version: 5 because someone else updated it first. The request has no If-Match header. Which status code fits?
  9. Not answered. A client sends a conditional update with If-Match: "v5" to avoid lost updates, but the resource's current ETag is "v7". Per RFC 9110, which 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. Which status code is most precise?
  11. Not answered. A client goes over its rate limit. Which status code should the server return, and which header tells the client when to try again?
  12. Not answered. Which response change is backward compatible, so you can ship it to existing clients without a new API version?
  13. Not answered. Per RFC 9457 (Problem Details for HTTP APIs), what media type goes in the Content-Type header of 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 main problem?