<\/p>\n
As a developer, you want APIs that are well designed, intuitive, and easy to use. But you may encounter APIs that fall short on one or more of these dimensions, particularly in applications that combine data and services from multiple sources. The Azure REST API Guidelines<\/a> establish the design principles and API patterns to ensure that Azure APIs are well designed, intuitive, and easy to use. But ensuring that service teams adhere to these guidelines becomes challenging to apply as the number of Azure services continues to expand, teams become more distributed, and our API surface area grows.<\/p>\n One challenge that we face is driving consistency in how our API definitions are written. Often, the API definitions are built by different individuals and teams within the same organization, and over time, can become large and complex. For example, the Azure Cognitive Services Metrics Advisor REST API definition<\/a> is almost 7,000 lines! In addition to consistency and size, we also struggle with reuse. While reuse is relatively easy in code, it’s challenging when working with OpenAPI documents.<\/p>\n And Microsoft isn’t alone in these challenges. Many organizations are struggling through finding answers for how to build and manage APIs at scale. We’re seeing an emerging set of companies and tools that are working to provide solutions to difficult problems. One tool that Microsoft is beginning to have success with is Cadl<\/a>, a new language for describing APIs.<\/p>\n Unlike other tools in the API space, Cadl is a language with a syntax that is similar to TypeScript, but built explicitly for describing APIs. In fact, we sometimes describe Cadl as “TypeScript for OpenAPI”. Because Cadl is a language, it provides many benefits that other tools don’t.<\/p>\n Authoring your API, you can compile your Cadl file to emit a complete OpenAPI definition that can be used to drive your existing tool chain. Cadl ensures that your API definition is correct and accurate. Just like you can’t compile a C# class with errors, you can’t produce an OpenAPI definition that doesn’t adhere to your rules and guidelines. By using Cadl, all of your APIs will be “correct by construction.”<\/p>\n The code for this example is located at cadl-demo<\/a>, and originated from the Http example in the Cadl-playground<\/a>. It will help accelerate your understanding of this post if you load up this example and get familiar with Cadl. Cadl has rich tooling support in VS Code and Visual Studio, which gives developers full language support and makes refactoring APIs super easy. We’ll use VS Code and the OpenAPI extension for the rest of this post. We’ll also use examples from the Azure REST API Guidelines<\/a> to illustrate how you can codify your own API standards.<\/p>\n Open the Cadl docs<\/a> and select the Installation tab<\/a> and then follow the steps there to install the tools and create a new Cadl project. The new empty Cadl project should contain:<\/p>\n Next, we’ll create our initial Cadl file using the Cadl playground<\/a>. The Cadl playground is a great place to experiment with and share simple Cadl definitions. Open the playground and select the Http service<\/strong> example. View the Swagger UI by choosing it from the dropdown in the right pane. We’ll make a few small changes that will help illustrate some points later in the discussion:<\/p>\n The result should look like this:<\/p>\n Copy the Cadl from the playground to the Most services will have more than one resource (model) and endpoint. In this example, we’ll add the Now we want to add an endpoint for our new Let’s use the power of the Cadl language to define an interface template<\/em> that can be reused across all of our resources. We’ll create a new We’ll move the Back in the Notice that we kept the At this point, it’s worth noting that our Cadl definition is a mere 51 lines across two files but produces an OpenAPI definition that is 470 lines\u2014an order of magnitude difference.<\/p>\n Next let’s look at how Cadl allows you to build API guidelines into your Cadl library. Organizations often create API guidelines to establish patterns for APIs that are well-designed, intuitive, and easy to use. Here, we’ll use Azure’s REST API guidelines<\/a> as an example.<\/p>\n Azure’s API guidelines<\/a> require an operation error response to have a standard structure and contents, in particular:<\/p>\n \u2705\u00a0DO\u00a0return an\u00a0 \u2705\u00a0DO\u00a0provide a response body with the following structure<\/p>\n The error response in our current Cadl definition doesn’t meet these requirements, but that is easily remedied with a few changes to the error model in We’ve also added Next, we’ll tackle the standard operations in our \u2705\u00a0DO\u00a0structure the response to a list operation as an object with a top-level array field containing the set (or subset) of resources.<\/p>\n \u2705\u00a0DO\u00a0return a\u00a0 \u2611\ufe0f\u00a0YOU SHOULD\u00a0use\u00a0value\u00a0as the name of the top-level array field unless a more appropriate name is available.<\/p>\n Azure also requires all operations to be idempotent, including creates. Most resources also need to support an update operation and a delete operation. Azure’s specific guidelines are:<\/p>\n \u2705\u00a0DO\u00a0ensure that\u00a0all\u00a0HTTP methods are idempotent.<\/p>\n \u2611\ufe0f\u00a0YOU SHOULD\u00a0use PUT or PATCH to create a resource. These HTTP methods are easy to implement, allow the customer to name their own resource, and are idempotent.<\/p>\n \u2705\u00a0DO\u00a0create and update resources using PATCH [RFC5789] with JSON Merge Patch\u00a0(RFC7396)\u00a0request body.<\/p>\n \u2705\u00a0DO\u00a0return a\u00a0204-No Content\u00a0without a resource\/body for a DELETE operation.<\/p>\n Once again, we can comply with all the above guidelines with some straightforward changes to the Here’s what the Change is inevitable in all things including APIs, and Azure requires all APIs to implement explicit versioning support in the form of a required \u2705\u00a0DO\u00a0use a required query parameter named\u00a0 \u2705\u00a0DO\u00a0use\u00a0“YYYY-MM-DD”\u00a0date values, with a\u00a0 Since the Then we add the But we’re not yet fully in compliance with the API versioning requirements, because there’s still the Cadl allows libraries to define a function that checks a Cadl program for specific patterns and issue diagnostics (linter messages). Typically, these linter functions are written in TypeScript and then compiled and run as JavaScript as part of the Cadl compilation. For expediency, we’ll implement our linter in JavaScript directly, but we don’t endorse this approach for a production Cadl library.<\/p>\n We’ll implement our linter in a file called With the linter now included in our library, In this post, we’ve taken you through some of the key value propositions of Cadl:<\/p>\n All these features add up to a system that enables developers to build APIs that are well designed, intuitive, and easy to use.<\/p>\n There’s much more to share on Cadl, such as how to create standalone libraries that can be reused across many projects, advanced API patterns, creating customer emitters, and more. Look for more posts on Cadl coming soon!<\/p>\nThe Cadl value proposition<\/h2>\n
\n
Create an API design with Cadl<\/h2>\n
Get started<\/h3>\n
package.json # Package manifest defining your cadl project as a node package.\r\ncadl-project.yaml # Cadl project configuration letting you configure emitters, emitter options, compiler options, etc.\r\nmain.cadl # Cadl entrypoint<\/code><\/pre>\n\n
version: 1.0.0<\/code> to the service decorator<\/li>\n@key<\/code> to @path<\/code> on the id<\/code> property in the Widgets model<\/li>\n@route(\"\/widgets\")<\/code> and @tag(\"Widgets\")<\/code> to the Widgets interface<\/li>\n@route<\/code> from read<\/li>\n@get customRead<\/code> operation with @route(\"analyze\") @post analyze()<\/code> that returns string | Error<\/code>;<\/li>\n<\/ul>\nimport \"@cadl-lang\/rest\";\r\n\r\n@service({\r\n title: \"Widget Service\",\r\n version: \"1.0.0\"\r\n})\r\nnamespace DemoService;\r\nusing Cadl.Http;\r\n\r\nmodel Widget {\r\n @path id: string;\r\n weight: int32;\r\n color: \"red\" | \"blue\";\r\n}\r\n\r\n@error\r\nmodel Error {\r\n code: int32;\r\n message: string;\r\n}\r\n\r\n@route(\"\/widgets\")\r\n@tag(\"Widgets\")\r\ninterface Widgets {\r\n @get list(): Widget[] | Error;\r\n @get read(@path id: string): Widget | Error;\r\n @post create(...Widget): Widget | Error;\r\n @route(\"analyze\") @post analyze(): string | Error;\r\n}<\/code><\/pre>\nmain.cadl<\/code> file in your VS Code project. Now you can run cadl compile .<\/code> in your VS Code terminal and it will produce an openapi.json<\/code> file in the cadl-output<\/code> directory with your generated OpenAPI 3 definition. If you open the openapi.json<\/code> in VS Code and then open the Swagger UI view, it should look exactly like the view in the Cadl playground.<\/p>\nAdd gadgets<\/h3>\n
Gadget<\/code> resource to our API definition. Using Cadl, it’s easy to add another model:<\/p>\nmodel Gadget {\r\n @path id: string;\r\n height: float32;\r\n width: float32;\r\n color: \"green\" | \"yellow\";\r\n}<\/code><\/pre>\nGadget<\/code> resource. We could copy and paste the Widgets<\/code> interface, but then, we’d have to copy\/paste the same operation definition for all endpoints! As developers, we prefer a way to define something once, and reuse it wherever we need it. Cadl supports this type of reuse for most API elements.<\/p>\nBuild a Cadl library<\/h2>\n
library.cadl<\/code> file to contain this template and any common definitions. When a developer defines and new resource, they can define all the standard operations for the resource by extending<\/em> the resource template interface. In this way, when the Cadl file is compiled, and the OpenAPI document emitted, it will have the required operations, constructed in exactly the way we defined them.<\/p>\nError<\/code> model from the main.cadl<\/code> to the new file and then define an interface template that defines a list<\/code>, create<\/code>, and get<\/code> operation similar to our Widgets<\/code> interface, using a type parameter in place of the Widget<\/code> model. The library.cadl<\/code> now looks like:<\/p>\nimport \"@cadl-lang\/rest\";\r\n\r\nusing Cadl.Http;\r\n\r\n@error\r\nmodel Error {\r\n code: int32;\r\n message: string;\r\n}\r\n\r\ninterface ResourceInterface<T> {\r\n @get list(): T[] | Error;\r\n @get read(@path id: string): T | Error;\r\n @post create(...T): T | Error;\r\n }<\/code><\/pre>\nmain.cadl<\/code> file, we can now use the new ResourceInterface<\/code> template for both Widgets<\/code> and Gadgets<\/code> as follows:<\/p>\n@route(\"\/widgets\")\r\n@tag(\"Widgets\")\r\ninterface Widgets extends ResourceInterface<Widget> {\r\n @route(\"analyze\") @post analyze(): string | Error;\r\n}\r\n\r\n@route(\"\/gadgets\")\r\n@tag(\"Gadgets\")\r\ninterface Gadgets extends ResourceInterface<Gadget> {\r\n}<\/code><\/pre>\nanalyze<\/code> operation of Widgets<\/code> because it isn’t part of the “standard” interface for all resources.<\/p>\nIntegrate API guidelines<\/h2>\n
Error response<\/h3>\n
x-ms-error-code<\/code>\u00a0response header with a string error code indicating what went wrong.<\/p>\nlibrary.cadl<\/code>. Since all operations are already using this one error model, we only need to make the change in this one place. Here’s the new definition that complies with the above guidelines:<\/p>\n@error\r\n@doc(\"Error response\")\r\nmodel Error {\r\n @doc(\"A server-defined code that uniquely identifies the error.\")\r\n @header(\"x-ms-error-code\")\r\n code: string;\r\n @doc(\"Top-level error object\")\r\n error: ErrorDetail;\r\n}\r\n\r\n@doc(\"Error details\")\r\nmodel ErrorDetail {\r\n @doc(\"A server-defined code that uniquely identifies the error.\")\r\n code: string;\r\n @doc(\"A human-readable representation of the error.\")\r\n message: string;\r\n @doc(\"An array of details about specific errors that led to this reported error.\")\r\n details?: ErrorDetail[];\r\n}<\/code><\/pre>\n@doc<\/code> decorators on the models and properties to produce descriptions on these elements in the generated OpenAPI, which will be shown in the REST API documentation generated from the OpenAPI.<\/p>\nStandard operations<\/h3>\n
ResourceInterface<\/code> template. The Azure API Guidelines<\/a> require the response of a list operation to have a specific structure that supports extension and pagination (where needed). Specifically:<\/p>\nnextLink<\/code>\u00a0field with an absolute URL that the client can GET in order to retrieve the next page of the collection.<\/p>\nlibrary.cadl<\/code> file:<\/p>\n\n
list<\/code> operation to use the new response model.<\/li>\ncreate<\/code> operation to use the put method.<\/li>\nPatch<\/code> model.<\/li>\nvoid<\/code>, which becomes a 204 response.<\/li>\n<\/ul>\nResourceInterface<\/code> looks like in our library.cadl<\/code> file. Notice that it has all the standard operations you would expect. GET<\/code> operations for the collection, a GET<\/code> with an id<\/code> for a specific resource, and the create, update, and delete operations with PUT<\/code>, PATCH<\/code>, and DELETE<\/code> respectively. Here’s the changed section of library.cadl<\/code>:<\/p>\nmodel List<T> {\r\n @doc(\"List of elements\")\r\n value: T[];\r\n @doc(\"A link to the next page of results if present.\")\r\n nextLink?: url;\r\n}\r\n\r\nmodel Patch<T> {\r\n @header contentType: \"application\/merge-patch+json\";\r\n ...T;\r\n}\r\n\r\ninterface ResourceInterface<T> {\r\n @get list(): List<T> | Error;\r\n @get read(@path id: string): T | Error;\r\n @put create(...T): T | Error;\r\n @patch update(...Patch<T>): T | Error;\r\n @delete delete(@path id: string): void | Error;\r\n}<\/code><\/pre>\nAPI versioning<\/h3>\n
api-version<\/code> query parameter on every operation. Here are some of the specific requirements from the Azure API Guidelines<\/a>.<\/p>\napi-version<\/code>\u00a0on every operation for the client to specify the API version.<\/p>\n-preview<\/code>\u00a0suffix for preview versions, as the valid values for\u00a0api-version<\/code>.<\/p>\napi-version<\/code> query parameter must be passed on all operations, it makes sense to define it once in the library.cadl<\/code> file. Here’s what that might look like:<\/p>\nmodel ApiVersion {\r\n @doc(\"The version of the API in the form YYYY-MM-DD\")\r\n @query(\"api-version\") apiVersion: string;\r\n}<\/code><\/pre>\napiVersion<\/code> parameter to each operation in the ResourceInterface<\/code> template using the spread<\/em> operator on the ApiVersion<\/code> model. Changing the template ensures that all the Widgets<\/code> and Gadgets<\/code> operations that derive from the template come into compliance with the above guidelines.<\/p>\ninterface ResourceInterface<T> {\r\n @get list(...ApiVersion): List<T> | Error;\r\n @get read(@path id: string, ...ApiVersion): T | Error;\r\n @put create(...T, ...ApiVersion): T | Error;\r\n @patch update(...Patch<T>, ...ApiVersion): T | Error;\r\n @delete delete(@path id: string, ...ApiVersion): void | Error;\r\n}<\/code><\/pre>\nanalyze<\/code> operation of the Widgets<\/code> interface over in main.cadl<\/code> that doesn’t have an api-version<\/code> parameter. And as the API continues to grow, there may be other operations outside library.cadl<\/code> that we need to make sure include an api-version<\/code> parameter. Cadl has a solution for this problem: built-in linter support.<\/p>\nLint with Cadl<\/h3>\n
linter.js<\/code>, which we import into library.cadl<\/code> to activate it. Our linter will use functions from the @cadl-lang\/lint<\/code> library so we need to install that library in our project. You can see the full source code for linter.js<\/code> in the cadl-demo project<\/a>. Here are a few key points to focus on:<\/p>\n\n
version-policy<\/code> diagnostic, which will be issued when the linter finds an operation without an api-version<\/code> query parameter.<\/li>\napi-version<\/code> parameter–its name, it’s required (not optional), and it’s a string type.<\/li>\nversionPolicyRule<\/code>, which checks each operation (line 26) to see if “some” parameter is an apiVersion<\/code> parameter and a query parameter. If not, the diagnostic is issued.<\/li>\ncadl compile .<\/code> will issue a diagnostic and fail the compile if any operation is missing the api-version<\/code> query parameter:<\/p>\n>cadl compile .\r\nCadl compiler v0.38.3\r\n\r\n\/Users\/mikekistler\/Projects\/mikekistler\/cadl-demo\/main.cadl:27:3 - error myLibrary\/version-policy: Every operation must have a required 'api-version' query parameter\r\n> 27 | @route(\"analyze\") @post analyze(): string | Error;\r\n | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\r\n\r\nFound 1 error.<\/code><\/pre>\nSummary<\/h2>\n
\n