Design and Build Great Web APIs

Learning the Role of Description Formats

A good API description provides a solid foundation for implementing the API itself. It converts all those requirements and feature requests we gathered in Chapter 3, ​Modeling APIs​, into a standardized and understandable document that we can safely share with others in the organization and on our team.

It’s important to have a shared description of the API because API designers and API builders may not always have a chance to talk to each other directly. Consider situations when the designer works on another team, in another office building, or in a location across the world. At times, API builders may need clarification about some aspect of the design, but it may not be practical to reach the right ...