Whenever APIs need to be communicated among various stakeholders, APIs needs to be described in some from. Thus, it should be as easy as possible to describe APIs. Specialized languages can support the crafting of useful API descriptions by providing appropriate abstractions and language concepts. Such specialized languages are API description languages.
In their short history, the role of API description languages has changed significantly. The original purpose of API description languages was a language for creating API documentation, in a similar way as JavaDoc provides a language for documenting Java programs. Today, API description languages can be used for many additional purposes during the design and development process of APIs, not only for their original purpose of generating a pretty documentation.
API description languages are machine readable specifications of the API. Machine readable specifications can be used for automating tasks in API development. If used correctly, automation has the potential to increase the productivity of API development. We will see more examples for increasing the efficiency of API development later. Here is just a small example as an appetizer:
The API description can be used for the partially automated generation of code for the API. The API description thus has the potential to support the API provider. The same API description can also be used for the automated generation of client-stub-code for the app consuming the API. This time the consumer is supported by the same API description.
If used correctly, API description languages are very powerful tools that can be far more than just languages. They can serve as the “single source of truth” and as the main reference for all aspects of API design and development.
To learn more about API description languages, check out the Swagger & OpenAPI 2.0 Quick Guide.
