Binary Semaphorelearn
sign in

System Design Notebook / 08

REST API Design

Designing an interface for someone you will never meet

An interface is a promise to someone you will never meet. Fielding's constraints and which one nobody implements, resources and the methods that act on them, status codes a client can act on, and what a well-behaved error looks like.

pages
99
sections
55
editions
Reading, Print, Tablet

Sign in to read it

Sign in and the whole notebook opens, all three editions with it. An account is what makes a download belong to someone.

Sign in with GitHub or Google

Start reading

How to use this book

Start reading

What is inside

Every section, and every one of them opens in the browser. Nothing here is hidden: if a section you need is not in this list, the notebook is not the right one and you should not spend a week on it.

  1. How to use this book
  2. The whole picture on one page
  3. 1The requirement: an interface two strangers agree on
  4. 21990 to 1993: the web outgrows its inventor
  5. 3Fielding's six constraints
  6. 4Why it is called REST
  7. 5The constraint nobody implements
  8. 6Finding the nouns
  9. 7Anatomy of a URL
  10. 8Plural nouns, and where the rule breaks
  11. 9The slash means containment
  12. 10Slugs, and the two problems the lecture skips
  13. 11Path or query, and what an id should look like
  14. 12Versioning: what actually forces a v2
  15. 13Safe, idempotent, and the difference nobody draws
  16. 14GET, and the day Google deleted a company's data
  17. 15POST, and why it is the odd one
  18. 16PUT and PATCH: replace against modify
  19. 17PATCH is not idempotent, and the lecture says it is
  20. 18What a PATCH body actually is
  21. 19DELETE, and the 404 on the second call
  22. 20Making POST retryable: idempotency keys
  23. 21200, 201, and the Location header
  24. 22204, and when an empty body is wrong
  25. 23404, and the collection that is empty
  26. 24400 against 422: which kind of wrong
  27. 25401 against 403, and the misleading name
  28. 26409, and the duplicate you did not plan for
  29. 27The lost update, and the two headers that prevent it
  30. 28202, 429, and the responses that ask the client to wait
  31. 29One error shape, everywhere
  32. 30Three features, one endpoint
  33. 31The envelope: what wraps your data
  34. 32Offset pagination, and the page-2 bug
  35. 33Keyset pagination
  36. 34`total` costs a second query
  37. 35Sorting, and the index underneath it
  38. 36Filtering, operators, and the namespace collision
  39. 37The unbounded limit
  40. 38Sane defaults: sending nothing must work
  41. 39The action that is not a verb on a noun
  42. 40Designing a custom action
  43. 41Custom actions are not REST, and that is fine
  44. 42The API-level N+1, and why GraphQL exists
  45. 43The second endpoint should cost nothing to learn
  46. 44Naming, and the standard that does not exist
  47. 45Design first: the interface before the code
  48. 46OpenAPI, and documentation that cannot go stale
  49. 47Reviewing an API diff
  50. 48The delivery script
  51. 49Whiteboard: designing an API live
  52. 50Follow-up question bank
  53. Appendix A. Status codes to memorise
  54. Appendix B. The design checklist
  55. Appendix C. Glossary
  56. Appendix D. Self-test

How to read it

Read with a pen. Every notebook opens with a question to answer before you start and asks you to redo the answer at the end, and the margin in the Print edition exists so you have somewhere to be wrong first. The Tablet edition is 16:9 with vector text, so note apps draw on it rather than treating it as a photograph.

more notebooks