Microsoft’s Streamlined API Design Language Gets a New Name and Expands Its Role in REST, OpenAPI, gRPC, and More
Some time ago, I discussed Microsoft’s efforts to enhance the Azure APIs. This initiative aimed to simplify connecting applications to the cloud by generating API definitions and SDKs automatically. By doing so, developers could efficiently manage Azure services through code, reducing manual work and enhancing integration. This approach marked a significant step forward in making API-based cloud management more accessible and scalable for developers.
At the core of this initiative was a new language developed by Microsoft called CADL—Concise API Design Language. CADL was designed to build upon the foundations of TypeScript and Bicep, offering a powerful way to define APIs. By using code to define API operations, CADL allowed developers to compile the results into OpenAPI definitions, effectively reducing the complexity of API development. CADL also enabled the establishment of guardrails and common definition standards as libraries, fostering collaboration between architects and developers on API designs. Its power was evident in how it could convert 500 lines of an OpenAPI definition into a mere 50 lines of code, streamlining the process of building robust APIs.
CADL and similar tools play a crucial role in maintaining massive platforms like Azure, which often need to recompile their APIs multiple times a day. These platforms rely on consistent APIs that are consumed by users, services, and various applications. In such a complex environment, having well-defined APIs is vital not only for the platform’s functionality but also for the ecosystem of developers who build on top of it. Public OpenAPI definitions, in particular, need to be accurate, as they form the backbone of automated tests and documentation generation.
The need for documentation is a critical aspect for developers working with APIs. Writing thorough documentation is time-consuming, and not every development team has the bandwidth to dedicate to it. CADL addressed this issue by producing both machine-readable endpoints and usable documentation simultaneously. This automation helps streamline the development process and ensures that developers have access to the information they need, without the additional overhead of manual documentation efforts.
This dual function of generating both API definitions and documentation is a game-changer. It simplifies the deployment of APIs by providing clear, consistent definitions while also creating developer-friendly documentation. This is particularly useful in environments like Azure, where APIs evolve rapidly, and maintaining up-to-date documentation would otherwise be a daunting task. The automation of documentation ensures that developers can always access the latest information about an API, reducing the friction typically associated with using evolving services.
In addition to its role in Azure, CADL’s influence is expanding beyond just Microsoft’s cloud services. Recently renamed TypeSpec, this streamlined API design language is set to play an even larger role in building services like REST, OpenAPI, gRPC, and more. By offering a concise and powerful language for defining APIs, TypeSpec is helping developers across industries create consistent, well-structured APIs that can easily be integrated into various platforms and services. As APIs continue to grow in importance across the software development landscape, tools like TypeSpec are paving the way for more efficient and scalable API design