Introducing Cadl: Microsoft’s concise API design language

Published on Dec 23, 2022

A 500-line OpenAPI definition can be written in 50 lines of code using Cadl. Architects and developers can construct and constrain APIs in this manner.

The advantage of Microsoft’s work at scale in Azure is that it will find problems much earlier and solve them much faster than we can. We may not have seen these solutions for years until they were finally integrated into Visual Studio tools. As a result of Microsoft’s conversion to open source, solutions are designed in the open and shared with the rest of the world via GitHub.

There is a major problem in the design of APIs and finding ways to make all the APIs from Azure consistent. Even API definitions written using OpenAPI can be complex and large; some API definitions from Azure are several thousand lines long. In spite of the same approach and guidelines, API definitions from different teams will emphasize different elements and offer different approaches to performing similar functions.

In order to ensure that APIs are consistent and documentation and tests can be automated, Azure recompiles its API surface at least once a day. This ensures that developers familiar with one set of APIs will not have to learn entirely new techniques when adding additional services to an application if they are familiar with a single set of APIs.

Bringing inconsistent API definitions into our applications using OpenAPI tools to generate the appropriate endpoints is a problem for those of us working at the other end of the service. It becomes even more challenging when we need to move beyond REST to GraphQL and to gRPC as our APIs evolve and require more than HTTP access.