Home / Blog

Microsoft’s concise API design language

William Tsu
Data Analyst
Experienced data analyst working with data visualization, cloud computing and ETL solutions.
Janaury 16, 2023

Many institutions are working on discovering answers for how to create and govern APIs at scale, but when evaluating a design, reading a statement is seldom adequate; so invariably examine a use case to drive sure it skims obvious in context. There’s a benefit to Microsoft’s toil at scale in Azure: It will discover problems much early and decipher them extensively faster than the rest. In the past, we may not have noticed those explanations for years until they were ultimately brought in it into Visual Studio devices, extensively contemporary web applications expose APIs that customers can employ to interact with the application. Microsoft recently brought up Cadl, a language describing cloud assistance APIs and additional API description languages, and this language is let out to have a syntax identical to Typescript’s but is created particularly for illustrating and formulating APIs. According to Microsoft’s website, Cadl’s integrated development environment (IDE) wings can be added to the language server in Visual Studio and Visual Studio statute, these integrate syntax highlighting, go-to explanation, linting, and auto-completion, with Cadl, you can formulate a 500-line OpenAPI intent in 50 lines of tenet.  It’s an analytical technique for creators and innovators to build and restrain APIs, Microsoft requests an online “Cadl Playground” where users can make an effort out of Cadl code.

Good API design is significant in a microservices architecture because all data business between courtesies happens either through statements or API calls but currently, things are distinct, as Microsoft’s transformation to open source implies explanations are evolved in the open and shared with the remnant of the planet via GitHub. But you may confront APIs that tumble brief on one or reasonable of these dimensions, mainly in applications that combine databases and aid from substantial sources. One prominent crisis is API design and spotting routes to create all the APIs from Azure consistent, a current API description, even one written employing OpenAPI, can be complicated and large; some of Azure’s are several thousand lines extended. Even with the exact method and guidelines, API descriptions from various squads will accentuate various aspects and request distinct paths of working with equal operations, users can create API descriptions with Cadl utilizing Azure’s REST API policies. Cadl is being created on GitHub and is said to incorporate language aspects identical to well-understood programming languages like Typescript and C#, Cadl’s API descriptions are purported as concise, comprising substance notions.

The Cadl value proposition

Inconsistent descriptions are a difficulty for those of us working at the other rear of the assistance, bringing those API explanations into our applications utilizing OpenAPI mechanisms to induce the relevant endpoints. Unlike additional devices in the API space, Cadl is a language with a syntax that is identical to TypeScript but constructed explicitly for characterizing APIs. Sometimes Cadl is described as “TypeScript for OpenAPI” because Cadl is a language, it furnishes multiple advantages that different devices don’t. Tremendous tooling backing: IDE elongations in VS Code and Visual Studio comprise syntax highlighting, go-to explanation, linting, and auto-completion, extensible, originators can codify their API procedures and promising techniques into a pack of regulations that can be executed by Cadl. Creating Cadl a language brings in a lot of significance; it authorizes you to encapsulate architectural restrictions into ordinances and wrap typical constructs in libraries.

Composing your API, you can assemble your Cadl file to eject a complete OpenAPI connotation that can be employed to navigate your existing toolchain, Cadl assures that your API intent is accurate and precise at first glimpse, it’s a JavaScript-like language with some resemblances to .NET languages. Microsoft narrates it as “TypeScript for APIs,” aiming at it to be manageable to operate for anyone knowledgeable with C#. Microsoft has started to move much of its API expansion to a language named Cadl, which assists you to specify API configurations programmatically before collecting OpenAPI descriptions. The objective is to do for APIs what Bicep accomplishes for infrastructure, nourishing a route to repeatably equip API descriptions, by abstracting design from the definition, Cadl can fit out much more succinct consequences, insuring that the OpenAPI contrivance in outlets like Visual Studio can parse it fast and efficiently. It’s a lot uncomplicated to strengthen the Cadl code too, as it all matches on one screen with functionality grouped properly.

Like Microsoft’s different domain-specific languages, Cadl concessions from Microsoft’s long narrative as a transition devices firm, fit neatly into possession toolchains, and the familiar syntax, Cadl borrows numerous language components from widespread programming languages like TypeScript and C#, so it comfortable for creators to understand and use. You can consistently sum up Cadl elongations to the language server in Visual Studio and Visual Studio Code, assuring that you get consent from built-in syntax highlighting regulation culmination, and linting. Precisely like you can’t gather a C# lesson with misconceptions, you can’t elicit an OpenAPI description that doesn’t cling to your statutes and procedures. By employing Cadl, all of your APIs will be valid by construction and Cadl has affluent tooling authorization in VS Code and Visual Studio, which allows innovators whole language support and brings in refactoring APIs super manageable. We’ll use VS Code and the OpenAPI wing as it becomes even more of a problem when we need to go beyond REST to GraphQL and gRPC as our APIs evolve and mandate better than HTTP credentials.

Create an API definition with Cadl, use Cadl to implement standards

If you desire to interact with a computer or system to recover data or execute an operation, an API supports you articulate what you desire to that system so it can comprehend and accomplish the proposal. Writing API descriptions is merely part of the Cadl tale. Conceivably more significantly, it enforces API ideals on expansion squads by furnishing structures that must be employed to deliver an API. Cadl equips a simple path, to sum up, documentation to an API: Use the @doc assertion to incorporate documentation that can be taken out when developing documentation from the resulting OpenAI description, next defining the routes and aids employed by the API. Routes are the direction to the resource relative to the assistance URI and are tied to namespaces that wrap the API functions and the key to edifice norms into Cadl descriptions is to develop libraries and these let you organize reusable templates for common techniques with an exceptionally C#-like syntax.

Another benefit of an API is that you don’t have to understand the specifics of obscuring—how your resource is recovered or where it reaches from establishing Cadl is easy adequately. The compiler and CLI are facets of the exact npm-hosted application and once downloaded and put in, you can operate the CLI to ensconce the bundled Visual Studio and Visual Studio Code elongations. You’re currently ready to construct your first API description, employing the Cadl CLI to initialize your chore and it is abrupt and manageable, which is how Microsoft renders much of its Azure API documentation facilitating your API creators to operate this strategy to not just sum up documentation in the principal body of an API layout, but furthermore in any libraries you employ.

Working as middlemen between devices, APIs make an assortment of web derivatives available to millions of clients across the World Wide Web and the definition has to commence with assistance illuminations, providing the benefit of a title and, better significantly, a version digit. You can next sum up a server description with a URI for the endpoint that is useful for globally circulated strategies, this feature can count different parameters, such as the provinces in an API function, although this is developed with Azure in sense, it’s beneficial for any distributed technique with numerous endpoints.


Most industries use more than one API to bind applications and share data, some end up wanting an API administration device to support their supervision, distributing, and analyzing various APIs. The working tenet of an API is normally communicated through the request-response transmission between a customer and a server, counting on the request kind, the platform will process the proposal and communicate the consequence back to the customer application which transmitted the proposal. For example, if it is a data proposal, the outlet will transmit back the requested database, or if the demand is to carry out a detailed operation, it will pay back the outcome of that particular operation. Cadl equips highly extensible substance language primitives that can relate API shapes ordinary amongst REST, OpenAPI, etc Cadl allows designers to be opinionated about what an API can accomplish and provide and provides API innovators the independence to fast create a description that approximates what their code can perform. Cadl entitles both consumer developers and, conceivably additional notably, testing devices to engulf consistent API portrayals, Cadl also stimulates highly normal API layouts that adhere to best methods by edifice. It is primarily due to how Cadl creates URLs for service hails, abstracting APIs into regulation, and coming to it with knowledge using devices like Express could assist innovators to come to grips with a unique language.