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 and API designers 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.
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 more about API description languages, such as Swagger and RAML, check out my new book on API Architecture.