Principles of Web API Design: Delivering Value with APIs and Microservices

Chapter 13

Document the API Design

Documentation is the third user interface for APIs, and the most important.

— D. Keith Casey

Figure 13.1 The final step in the Refine phase is to produce robust documentation, incorporating learnings back into the API design.

Documentation is a very important element of the developer experience. Most API teams assume that reference documentation for each operation is sufficient. However, that is only the beginning of the API documentation effort.

Establishing an API documentation strategy is part of API design. Developer portals must support a variety of personas that all contribute to the success of an ...