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.

api description languages
Example of an API Description Language

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.

What are API Description Languages?

Matthias Biehl

As API strategist, Matthias helps clients discover their opportunities for innovation with APIs & ecosystems and turn them into actionable digital strategies. Based on his experience in leading large-scale API initiatives in both business and technology roles, he shares best practices and provides both strategic and practical guidance. He has stayed a techie at heart and at some point, got a Ph.D. Matthias publishes a blog at api-university.com, is the author of several books on APIs, and regularly speaks at technology conferences.