The Elements of APIs

By John Holdun, 2021–2024

Would you like the design a web API that is reliable and pleasant to use? I have some ideas for you.

  1. Introduction
  2. What problems are we trying to solve?
  3. A shortcut
  4. Establishing contracts
  5. Requests and Responses
  6. Resources
  7. Side effects
  8. Many nouns, few verbs
  9. Designing Data
  10. Relationships
  11. Discoverability
  12. Conclusion
  13. Appendix: Versioning your API
  14. Appendix: Versioning your Resources
  15. Appendix: Authentication
  16. Appendix: REST
  17. Appendix: JSON:API
  18. Appendix: Domain-Driven Design

Read as one page