Developing rich, cross-language SDKs for a cloud platform as featureful as Microsoft Azure is a tall order. Luckily AutoRest and the OpenAPI specification enable the Azure SDK team to generate much of the code needed for these SDKs using API specifications authored by Azure service teams. This article will give you more insight into how we use code generation to provide a great development experience for Azure users.

What is OpenAPI?

OpenAPI is a specification language that enables one to describe a web service API in terms of its operations and the data types it understands. It was originally conceived in 2011 as a specification called Swagger to enable generation of documentation and client libraries for the REST APIs of a company called Wordnik. Over time, more companies started using Swagger to describe their REST APIs and provide those same benefits to their own users.

The innovation in tooling around Swagger gradually led to greater adoption and the formation of the OpenAPI Initiative. This organization established OpenAPI version 2.0 (equivalent to the Swagger 2.0 specification) and then began developing the next iteration, OpenAPI version 3. This specification enabled a new level of expressiveness for describing patterns that were either vague or impossible to specify in OpenAPI version 2.

OpenAPI is primarily concerned with describing web services that follow the Representational State Transfer (REST) architectural model where operations are exposed via URI paths that accept HTTP verbs like GET, PUT, POST, and DELETE. These URI paths generally refer to “resources” understood by the service where the request and response bodies of most operations contain the details of the resource at that path. For example, a POST request with the body containing the desired state of a resource will create that resource, a PUT request with changes to some properties will update the resource, and a DELETE request will cause the resource to be deleted. OpenAPI provides a schema language which enables this type of API to be described in a machine-readable form, usually encoded in JSON.

Let’s imagine that we have a service for creating and querying some arbitrary resource called a “widget.” A widget resource has an ID and a name and can be created using the POST action on the /widgets URI. All widgets that have been created can be queried using a GET request on the /widgets URI and a specific widget can be queried with a GET to the specific URI for the ID like /widgets/1.

#azure sdk #autorest #openapi