Subscribe to Updates

    Get the latest creative news from FooBar about art, design and business.

    What's Hot

    France’s OVH expands into India amid growing cloud adoption

    March 21, 2023

    Governments request for user data from Apple, Google rises; India ranks no. 1 in Southern Asia: Report

    March 20, 2023

    Govt plans incentive scheme for cloud startups to thwart Microsoft, Amazon, and Google domination

    March 17, 2023
    Facebook Twitter Instagram
    Your Infotech
    • Data

      Governments request for user data from Apple, Google rises; India ranks no. 1 in Southern Asia: Report

      March 20, 2023

      How to back up all your Google account data

      March 15, 2023

      Employees Are Feeding Sensitive Biz Data to ChatGPT, Raising Security Fears

      March 8, 2023

      Google Search Console Bulk Data Export Is Here

      February 24, 2023

      AWS, Azure, and Google Cloud report single-digit YoY growth by annual contract value in Q4CY22

      February 13, 2023
    • Cloud

      France’s OVH expands into India amid growing cloud adoption

      March 21, 2023

      Govt plans incentive scheme for cloud startups to thwart Microsoft, Amazon, and Google domination

      March 17, 2023

      Intellect launches eMACH.ai for banks to use cloud services with embedded AI

      March 14, 2023

      Chinese AI groups use cloud services to evade US chip export controls

      March 9, 2023

      Tech-sponsored study criticizes plan to exclude non-EU cloud vendors

      March 6, 2023
    • Networking

      Amazon’s AWS cozies up to carriers to launch 2 services to build and operate networks in the cloud

      February 22, 2023

      META PLATFORMS SPENT OVER $1 BILLION ON ARISTA NETWORKING IN 2022

      February 17, 2023

      Microsoft Teams and Outlook are down due to a ‘networking issue’

      January 25, 2023

      Warning to those with older phones 3G networks are to be scrapped starting this year

      January 23, 2023

      Will the Broadband Ecosystem Save Telecom in 2023?

      January 19, 2023
    • Virtualization

      Imagination and Telechips drive automotive display diversity with hardware virtualization

      March 16, 2023

      Device virtualization is key to IoT adoption

      March 3, 2023

      Discover how virtualization can transform your business with this online training

      February 7, 2023

      Server Virtualization Software Market Next Big Thing | Major Giants IBM, Oracle, Microsoft

      February 2, 2023

      Global Data Virtualization Market Report 2022: Featuring Oracle, IBM, Cisco, Salesforce, Workday, Alteryx, Domo, Ceros, Cluvio & Qliktech International

      January 26, 2023
    • IT Infrastructure

      TCS+ | The need for speed: Braintree’s Heath Huxtable on modern IT infrastructure

      March 13, 2023

      The race to net zero: Six ways to slash IT infrastructure emissions

      March 10, 2023

      Vertiv and TechAccess partner to boost African IT infrastructure solutions

      February 28, 2023

      It Infrastructure Market Size 2023 Research Report with Technological Factors and Forecast till 2025

      February 21, 2023

      Geojit to build 1.25 lakh sq ft IT infrastructure in Infopark

      February 14, 2023
    Your Infotech
    Home»Cloud»Introducing Cadl: Microsoft’s concise API design language
    Cloud

    Introducing Cadl: Microsoft’s concise API design language

    yourinfotechBy yourinfotechDecember 30, 2022Updated:December 30, 2022No Comments7 Mins Read
    Facebook Twitter Pinterest LinkedIn Tumblr WhatsApp VKontakte Email
    Share
    Facebook Twitter LinkedIn Pinterest Email

    With Cadl, you can write a 500-line OpenAPI definition in 50 lines of code. It’s a logical way for architects and developers to construct and constrain APIs.

    There’s an advantage to Microsoft’s work at scale in Azure: It will find problems much earlier and solve them much faster than the rest of us. In the past, we may not have seen those solutions for years until they finally made it into Visual Studio tools. But now things are different, as Microsoft’s conversion to open source means solutions are designed in the open and shared with the rest of the world via GitHub.

    One big problem is API design and finding ways to make all the APIs from Azure consistent. A modern API definition, even one written using OpenAPI, can be complex and large; some of Azure’s are several thousand lines long. Even with the same approach and guidelines, API definitions from different teams will emphasize different elements and offer different ways of working with similar functions.

    With Azure recompiling its API surface at least once a day, it needs to ensure that APIs are consistent and that documentation and tests can be automated—as well as allowing a developer familiar with one set of APIs to not have to learn a whole new set of techniques when adding additional services to an application.

    [ Also on InfoWorld: What is an API? Application programming interfaces explained ]
    Inconsistent definitions are a problem for those of us working at the other end of the service, bringing those API definitions into our applications using OpenAPI tools to generate the appropriate endpoints. It becomes even more of an issue when we need to go beyond REST to GraphQL and to gRPC as our APIs evolve and require more than HTTP access.

    Introducing Cadl
    Microsoft has begun to move much of its API development to a language called Cadl, which helps you define API structures programmatically before compiling to OpenAPI definitions. The intent is to do for APIs what Bicep does for infrastructure, providing a way to repeatably deliver API definitions. By abstracting design away from the definition, Cadl can deliver much more concise outputs, ensuring that the OpenAPI tool in platforms like Visual Studio can parse it quickly and efficiently.

    What is Cadl? At first glance it’s a JavaScript-like language with some similarities to .NET languages. Microsoft describes it as “TypeScript for APIs,” intending it to be easy to use for anyone familiar with C#. Like Microsoft’s other domain-specific languages, Cadl benefits from Microsoft’s long history as a development tools company, fitting neatly into existing toolchains. You can even add Cadl extensions to the language server in Visual Studio and Visual Studio Code, ensuring that you get support from built-in syntax highlighting, code completion, and linting.

    Making Cadl a language makes a lot of sense; it allows you to encapsulate architectural constraints into rules and wrap common constructs in libraries. An API description won’t compile if it steps outside the bounds of your architectural rules, ensuring they’re enforced by the Cadl environment. API designers will need to work within the guidelines set by the architecture team, a process the Cadl designers describe as making outputs “correct by construction.”

    [ Attend Virtual Summit on November 8 – CIO’s Future of Cloud Summit: Mastering Complexity & Digital Innovation – Register Today! ]
    Like many Microsoft open-source projects, Cadl is being developed on GitHub, with clear and in-depth documentation. There’s even an online playground where you can experiment with Cadl code, comparing it with both OpenAPI and Swagger format outputs. You’ll quickly see that Cadl code can be a lot more concise than the OpenAPI output: A 34-line Cadl API description expands to 359 lines of OpenAPI. That’s 10 times larger. It’s a lot easier to maintain the Cadl code too, as it all fits on one screen with functionality grouped appropriately.

    Build an API definition with Cadl
    Installing Cadl is simple enough. The compiler and CLI are part of the same npm-hosted application. Once downloaded and installed, you can use the CLI to install the bundled Visual Studio and Visual Studio Code extensions. You’re now ready to build your first API definition, using the Cadl CLI to initialize your project. This runs you through a brief set of prompts to choose a base template, add a name, and pick a default library. A quick compilation tests that everything is in place, ready to work.

    Writing an API definition in Cadl is straightforward. You need to declare both the REST and OpenAPI bindings, usually in the main file of your Cadl code. In Cadl, keywords are called “decorators” and are prefixed with @, helping make files human-readable.

    Your definition needs to start with service definitions, giving a service a name and, more importantly, a version number. You can next add a server definition with a URI for the endpoint. Useful for globally distributed systems, this feature can add additional parameters, such as the regions in an API available. Although this is clearly designed with Azure in mind, it’s helpful for any distributed system with multiple endpoints.

    Next, define the routes and resources used by the API. Routes are the path to the resource relative to the service URI and are linked to namespaces that wrap the API operations. Operations are defined using the HTTP verb that’s expected or by function, for example, “list.” Where names are used, the compiler will add the appropriate verb when generating the API. These can define the request body of a REST API call, so you can use this to send JSON to a complex API, or just simple text for something relatively basic. The same process works for responses, too.

    For more complex APIs, an autoroute option can generate paths using parameters, for example where you’re passing usernames or IDs to an API that expects them in the path. You’re not limited to delivering parameters in paths; there’s an option to pass them as a URL query.

    The result is a relatively simple way to define your REST APIs, somewhat reminiscent of working with the Express node.js application framework. I suspect this is mainly due to how Cadl constructs URLs for service calls, abstracting APIs into code. Coming to it with experience using tools like Express could help developers come to grips with a new language.

    Using Cadl to enforce standards
    Writing API definitions is only part of the Cadl story. Perhaps more importantly, it enforces API standards on development teams by providing structures that must be used to deliver an API. The key to building standards into Cadl definitions is to create libraries. These let you manage reusable templates for common functions with a very C#-like syntax. It’s worth looking at how Microsoft uses these to implement Azure API features.

    For example, you can create a generic interface to define a REST API format, detailing the capabilities of an API. Once you have a library, you can extend your API interfaces to use the library template, mapping it to a route and tagging it appropriately. Next, use a model definition to create the API, listing any expected responses.

    Cadl provides a simple way to add documentation to an API: Use the @doc statement to include documentation that can be extracted when creating documentation from the resulting OpenAI definition. It’s quick and easy, which is how Microsoft generates much of its Azure API documentation. Encourage your API designers to use this approach to not only add documentation in the main body of an API design, but also in any libraries you use.

    There’s a lot to like in Cadl. It’s one of those domain-specific languages you look at and think, “Why wasn’t that here already?” By providing a logical way to both construct and constrain APIs, Cadl lets architects be opinionated about what an API can do and deliver and gives API developers the freedom to quickly build a definition that matches what their code can do. Cadl allows both client developers and, perhaps more importantly, testing tools to consume consistent API definitions.

    Share. Facebook Twitter Pinterest LinkedIn Tumblr WhatsApp Email
    Previous ArticlePublic cloud repatriation trends are gaining ground and can’t be ignored
    Next Article QTS Data Center provides residual heat to 10,000 buildings and educational institutions
    yourinfotech
    • Website

    Related Posts

    France’s OVH expands into India amid growing cloud adoption

    March 21, 2023

    Govt plans incentive scheme for cloud startups to thwart Microsoft, Amazon, and Google domination

    March 17, 2023

    Intellect launches eMACH.ai for banks to use cloud services with embedded AI

    March 14, 2023

    Chinese AI groups use cloud services to evade US chip export controls

    March 9, 2023

    Leave A Reply Cancel Reply

    Our Picks

    Subscribe to Updates

    Get the latest creative news from Your Infotech about Information Technology.

    About Us
    About Us

    We provide a wide range of customized, integrated B2B and B2C digital marketing services solutions that are ideal for your business.

    We're accepting new partnerships right now.

    Email Us: info@yourmartech.com
    Contact: +1-530-518-1420

    Our Brands
    • Your Martech
    • Your HR Tech
    • Your Fin Tech
    • Your Revenue
    • Your Bio Tech
    • Your POS Tech
    • Your Health Tech
    SUBSCRIBE NOW
    Loading
    LinkedIn
    • Privacy Policy
    © 2023 Vigarbiz Inc. Designed by Vigarbiz Media.

    Type above and press Enter to search. Press Esc to cancel.