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.

Another handy aspect of description formats is that they don’t depend on any single technology, document format, or API style. They simply describe the data to be passed back and forth (givenName, familyName, userId) and the actions that should be available (approveUser, updateCompany, cancelOrder). API descriptions provide enough information to tell everyone what must be done, but they leave the how to do it up to the API developers.

Descriptions allow us to share enough information with all parties without prematurely deciding how that information will be used. Let’s ...