Learning the Role of Description Formats

API description

A good API description provides a solid foundation for implementing the API itself. It converts all the requirements and feature requests 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 aspects of the design, but it may not be practical to reach the right person right when we need them. That’s when a good API description document comes in handy.