API Design Middle interview questions and answers

75 questions for a API Design (Middle) interview - with correct answers, explanations and links to the docs.

Take this quiz
  1. 1.How would you model 'cancel an order' in a REST API?
  2. 2.When should a relationship be its own resource, like /users/42/memberships?
  3. 3.How should a JSON Merge Patch request treat null?
  4. 4.What does JSON Patch (RFC 6902) look like?
  5. 5.How can a REST API let clients load related resources in one request?
  6. 6.What does sparse fieldsets (?fields=id,name,email) give clients?
  7. 7.Why might an API use UUIDs or opaque string IDs instead of auto-increment integers in URLs?
  8. 8.How should an API represent money?
  9. 9.How should validation errors for several fields be reported?
  10. 10.Why should error codes in the body be stable and documented?
  11. 11.What's the right status for a request that's well-formed but violates a business rule, like 'can't ship an unpaid order'?
  12. 12.Should an API return 403 or 404 when a user requests another user's private resource?
  13. 13.Why does offset pagination produce duplicates or gaps when items are inserted while paging?
  14. 14.Why is returning a total count with every page sometimes a problem?
  15. 15.What's important for a cursor-paginated list's sort order?
  16. 16.How can an API offer flexible filtering without becoming a query language nobody can optimize?
  17. 17.How should sort parameters usually look?
  18. 18.How does an idempotency key work on the server?
  19. 19.Two clients edit the same document. How can an API prevent one from silently overwriting the other?
  20. 20.What does 304 Not Modified save?
  21. 21.Why are retries dangerous for non-idempotent operations without protection?
  22. 22.What does Cache-Control: private, max-age=60 mean?
  23. 23.What's the difference between no-cache and no-store?
  24. 24.What does stale-while-revalidate allow?
  25. 25.Why is the Vary header important for caching API responses?
  26. 26.What counts as a breaking change in a REST API?
  27. 27.What is Hyrum's Law?
  28. 28.What are trade-offs of URL versioning (/v2/...) versus header versioning?
  29. 29.How can you evolve a field's format without a new major version?
  30. 30.What's the difference between authentication and authorization in an API?
  31. 31.What does OWASP API1:2023 Broken Object Level Authorization describe?
  32. 32.What is Broken Object Property Level Authorization (OWASP API3:2023)?
  33. 33.Why should access tokens be short-lived?
  34. 34.What are OAuth scopes used for?
  35. 35.How should service-to-service calls inside a system be authenticated?
  36. 36.Why should rate limits be applied per client (API key or user) rather than only per IP?
  37. 37.What does OWASP API4:2023 Unrestricted Resource Consumption cover?
  38. 38.What's a good client behavior when it receives 429 or 503?
  39. 39.How should a webhook receiver verify that a request really comes from the provider?
  40. 40.Why should webhook handlers be idempotent?
  41. 41.Why should a webhook endpoint respond quickly and process the event asynchronously?
  42. 42.Can webhook events be assumed to arrive in order?
  43. 43.Why is HTTP caching harder with GraphQL than with REST?
  44. 44.How do GraphQL errors differ from REST errors?
  45. 45.How does GraphQL usually handle schema evolution?
  46. 46.When is tRPC a good choice?
  47. 47.What does AsyncAPI describe?
  48. 48.How should an API handle a bulk operation where some items fail?
  49. 49.Why might a large export be better as an asynchronous job than a single GET?
  50. 50.How can clients upload large files without sending them through the API server?
  51. 51.What makes API documentation genuinely useful?
  52. 52.How can you catch breaking changes in an OpenAPI spec automatically?
  53. 53.What are contract tests between a client and an API?
  54. 54.Why generate SDKs or clients from an OpenAPI spec?
  55. 55.How should an API handle time zones in inputs and outputs?
  56. 56.What's a sensible default for unknown query parameters?
  57. 57.Why should list responses have a stable default sort order?
  58. 58.What does a 'Backend for Frontend' change about API design?
  59. 59.What does an API gateway typically handle?
  60. 60.How should an API expose actions on many items, like 'archive 500 messages'?
  61. 61.Why include a correlation ID in error responses?
  62. 62.What's the risk of exposing internal error messages (e.g. SQL errors) to API clients?
  63. 63.When might PUT with a full document be better than PATCH?
  64. 64.Why should API responses avoid exposing nulls for fields that are 'not applicable' vs 'unknown' without documentation?
  65. 65.What is media type versioning?
  66. 66.What does the Prefer: return=minimal request header ask for?
  67. 67.Why can't an API respond with Access-Control-Allow-Origin: * to credentialed browser requests?
  68. 68.A browser SPA authenticates with cookies to its API. What extra protection is needed compared with bearer tokens?
  69. 69.How should an API provider store the API keys it issues?
  70. 70.When is POST /orders/search with a JSON body acceptable instead of GET with query parameters?
  71. 71.What is the /users/me (or /me) convention for?
  72. 72.When should an API return 410 Gone rather than 404?
  73. 73.What status fits a request body larger than the API allows?
  74. 74.Why does a stable operationId in OpenAPI matter?
  75. 75.How should webhook payloads be versioned?