OpenAPI Specification

OpenAPI Specification can be used to secure and accelerate the API lifecycle.

Big news in the world of APIs! Today, the Open API Initiative (OAI) released its 3.0.0 version of the OpenAPI Specification. In case you missed our past coverage of this evolving specification, the OpenAPI Spec (OAS) has quickly become an industry standard method to describe web APIs.

The OpenAPI Specification was transmuted from Swagger, and is now maintained by the OAI, a Linux Foundation organization with an impressive (and growing) number of member companies (nearly 30). According to the OAI charter, their goal is to build a “vendor-neutral, portable and an open specification for providing technical metadata for REST APIs.”

The actual development is overseen by the Technical Developer Community, who, as we’ve covered previously, has been busy working on a 3.0 draft for some time now. To commemorate the official v3.0.0 release, today we sat down with TDC member Ron Ratovsky to hear about the latest updates to the specification, and to learn his view on the future evolution of the API definition and its impact on the API economy at large.

Read the official v3 release announcement here

What’s New in v3?

We spoke with Ron Ratovsky, who is working with the TDC. He filled us in on a couple exciting, brand new features within the 3.0 version. First off he highlighted the new callback object, which allows API providers to define asynchronous APIs and webhooks — a smart advancement for the spec now that subscription-based and event-driven architectures have become prevalent.

Next, he spotlighted the link object; a brand new feature that allows one to “statically link responses to related operations, making it easier to traverse an API.” True HATEOAS zealots beware — according to Ratovsky, this isn’t hypermedia — rather, the new links object equates to better internal API referencing. Links can be in the form of fields such as operationRef, which references an OAS operation, requestBody, parameters, and other field types that help express relationships between operations.

On the whole, the OAS has been enhanced to embrace a simplified structure that promotes reusability. One of these enhancements is the redesign of parameters to allow for additional flexibility. This has brought better support for content negotiation, allowing an API to better document its ability to serve various media types to a client. In that vein, OAS v3 has complex types for all parameters, catering to nuanced developer needs.

With cyber vigilance forcing innovative, alternative API security measures throughout the industry, many will be pleased to see the OAS’s update to the Security Scheme Object. In v3, many schemes are supported as possible authentication mechanisms: HTTP Basic Authentication, API keys (as a header or query parameter), OAuth2 common flows, and OpenID Connect Discovery. An important addition is better support for bearer tokens like JWT, which have grown in popularity recently. Though several security options now exist and multiple ones can be used simultaneously, “only one of the security requirements objects must be satisfied to authorize a request.

When you are describing an API, having examples of possible returns and media types is a plus as it helps the developer user understand how it all functions. The biggest change to OAS since the Implementer’s draft published on February this year, according to Ratovsky, is how these examples can be represented. With OAS v3, the examples object is now a map, allowing you to provide multiple examples and descriptions.

Another major improvement is extended JSON Schema support. See the specification for a complete definition of the v3 schema, including descriptions of objects and fields. All these updates really pack a punch, and bring an expansive array of possibilities for the API host throughout the whole software lifecycle. According to Ratovsky:

“Organizations are able to use the specification to drive the API lifecycle with increased reusability, extended JSON support, and updated security features.”

You can read the full v3 feature list here

The Community Has Spoken

No update this large comes about swiftly; this latest release is the culmination of a 2 year timeline, involving many contributors, senior API architects, the TDC, and feedback from the entire developer community.

According to Ratovksy, many specifications and open source projects tend to follow a natural evolutionary process. Whether it was changes to the existing design, or suggestions for entirely new features, he notes that v3 was a product of an open forum approach:

“The majority of the updates came from user requests and contributions. The project, as any other open source project, was public and allowed anyone to contribute.”

Driving New Ecosystems

Growth of member companies that support OpenAPI Specification has grown 4X over the past year and a half. What’s fascinating is that we’re seeing adoption from previously technically intransigent sectors, like healthcare, government, and banking. It’s cool to see the inevitable API-fication of industries we’ve covered on the blog actually come to fruition.

“Healthcare is going through a data revolution right now with APIs at the top of the agenda”
-Mohamed Alkady, President at Hart.

On the subject of ecosystems, the OpenAPI Specification has fostered an ecosystem in its own right, enabling boundless opportunities for third party tooling for things like documentation generation, validation, specification authoring tools, and code generation. Obviously, these tools that process v2 won’t be able to process v3 without some adjustments, and should migrate to v3 as soon as possible.

Why? Utilization of new features such as callbacks and links will undoubtedly unlock new opportunities for tooling providers, easing the end API design experience. For example, SmartBear has begun implementing OAS3 support for their Swagger OSS tooling and their SwaggerHub platform.

Congratulations to The TDC and OAI

For this piece, we talked to Ron Ratovsky, who is a member of the Technical Developer Community (TDC) and the Technical Overview Board (TOB). As part of these working groups, Ron helped with reviewing changes to the specification, introducing new ones, organizing user requests, and overall overviewing of the process.

However, a very big congratulations is in order to all members of the Technical Developer Community (TDC) as well as contributors on Github for their work in helping evolve the 3.0 draft and release.

Since the OAI is now comprised of so many major companies that represent the needs of API developers, it has become a near de-facto method for describing RESTful APIs in today’s economy. As the specification continues to mature, we expect to see additional tooling, support, and innovative abilities emerge that will help accelerate seasoned API veterans as well as new entrants into the API space.

“The release of this third-generation format is a significant milestone for our community”

Reporting on the news of the day is great, but we’d like to hear from you. What do you think of the OAS? Has your organization adopted it as a way to describe your APIs? If so, is it meeting your company’s goals? Leave a comment below!

Bill Doerrfeld

About Bill Doerrfeld

Bill Conrad Doerrfeld is an API specialist, focusing on API economy research and marketing strategy for developer programs. He is the Editor in Chief for Nordic APIs, and formerly Directory Manager & Associate Editor at ProgrammableWeb. Follow him on Twitter, visit his personal website, or reach out via email.