API description languages are domain-specific languages, which are especially suited for describing APIs. They are both human-readable and machine-readable languages, much like programming languages. They are intuitive languages that can be easily written, read and understood by API developers, API designers, and API architects alike. Description languages are also precise, leave little room for ambiguity and are very expressive and powerful. They have a well-defined syntax, which makes it possible to process them automatically by software.
Are you designing RESTful APIs? Then learn why you need API description languages such as OpenAPI, Swagger or RAML.
And if you want to create an event-based architecture with RESTful APIs? Then you need a webhooks infrastructure. Get a complete description of you webhooks infrastructure in OpenAPI.
Compared to programming languages or API implementation languages, API description languages use a higher level of abstraction and a declarative paradigm. This means that they can be used to express the “what” instead of the “how”. For example, they define the data structure of the possible responses (the “what”), instead of describing how the response is computed (the “how”). This makes them very well suited for expressing the architecture of each API proxy in the portfolio and the design of the API portfolio as a whole.
To learn API description languages in-depth, check out my Book on Swagger & OpenAPI 2.0.
