BT

Facilitating the Spread of Knowledge and Innovation in Professional Software Development

Write for InfoQ

Topics

Choose your language

InfoQ Homepage News Microsoft Announces Preview of OpenAPI Specification V3 in Azure API Management

Microsoft Announces Preview of OpenAPI Specification V3 in Azure API Management

This item in japanese

Bookmarks

Recently Microsoft has announced support for the OpenAPI specification v3 in Azure API Management, which is their service that enables the set up, publishing, monitoring and maintainence of APIs. Support of the OpenAPI specification has been implemented through the OpenAPI.NET SDK and allows the abstraction of the definition of APIs from their implementation.

The OpenAPI specification, previously known as Swagger, provides the means to describe RESTful web services in a language independent way. As OpenAPI is widely adopted, a diverse ecosystem is available with tools for designing, documenting, building, testing and implementing governance. The specification gets overseen by the OpenAPI Initiative, owned by the Linux Foundation, and has a wide variety of organizations driving its development, including companies such as SmartBear, Microsoft, and WSO2. Anyone can follow or even contribute to the development of the specification on the GitHub repository of the OpenAPI Initiative.

According to Tom Kerkhove, Microsoft Azure MVP and Azure Architect, the specification has an important role when exposing APIs to their consumers.

Providing clean and well-documented APIs is a must. This allows your consumers to know what capabilities you provide, what they are for and what to expect. This is where the OpenAPI specification, aka Swagger, comes in and defines how APIs should be defined across the industry, regardless of what technology is underneath it.

Version 3 of the specification has brought several changes, and as such these are now also available for Azure API Management. For instance, this new version introduced a whole new architecture with components such as headers, links, and callbacks, taking a more modular approach in the definition, as described by Guy Levin, CTO at RestCase.

Version 3.0 of the API specification format has taken a much more modular, and reusable approach to defining the surface area of an API, enabling more power and versatility when it comes to describing the request and response models, as well as providing details on the common components that make up API usage like the underlying data schema and security definitions.

Another introduced option is to include callbacks to an operation, meaning it is now possible to describe webhooks for these. Finally, linking allows defining relationships between different paths of the APIs, providing the capability to expand on its attributes.

Image source: https://blog.restcase.com/6-most-significant-changes-in-oas-3-0/

Following the announcement, it is now possible to import OpenAPI v3 definitions in Azure API Management, albeit with some restrictions. Currently, this is possible through the portal or via the REST API. Subsequently, capabilities for exporting the OpenAPI descriptions are also available, either in the developer portal or using another call to the REST API.

Source: https://azure.microsoft.com/en-us/blog/announcing-the-preview-of-openapi-specification-v3-support-in-azure-api-management/

Eventually, before these capabilities will move into general availability, and it will also become possible to use the PowerShell SDK for doing both import and export of the definitions.

Rate this Article

Adoption
Style

BT