Final Release of OpenAPI 3.0 Specification is Coming Soon

The Open API Initiative (OAI), an open source project guided by The Linux Foundation, has announced that the final release of the OpenAPI 3.0 Specification is tentatively scheduled for the week of July 17. A two-week "last chance" period will begin on June 19 giving developers a final chance to try out OpenAPI 3.0 and propose changes to the spec.

The OAI was formed in 2015, and as part of the formation of the OAI, the Swagger specification was donated to the project by SmartBear Software. The Swagger specification was renamed the OpenAPI specification, and the current OpenAPI Specification (version 2) is semantically identical to the specification formerly known as Swagger 2.0. The OpenAPI Specification aims to define an interface to REST APIs, describing resources and operations in a format that is easily discoverable and understandable by both machines and humans.

The OpenAPI 3.0 Specification, which represents the first official departure from the Swagger 2.0 specification, will include some significant changes to structure, request parameters, protocol, payload, and documentation. The 3.0 spec also includes some new capabilities that were not part of version 2.0.

Version 3.0 includes a new callback object and links object so that hypermedia, web hooks, pub/sub and other types of APIs can be described beyond the simple HTTP model. The callback object was added because version 2.0 was criticized for not having a way to describe an outbound HTTP request along with its expected response. The links object makes it possible to describe which new resources may be accessed depending on the data that is retrieved from an initial resource.

An Open API Initiative blog post lists some of the fundamental changes in OpenAPI 3.0 including "Added support for Cookie parameters and eliminated dataForm parameters." Cookies were not formally supported in the 2.0 specification. However, because Cookies are technically a specially-formatted header, users could make things work. Officially adding Cookies to the 3.0 specification will make the definition and usage in tools significantly better.

We reached out to the Members of the Open API Initiative's Technical Developer Community who provided some details about the upcoming final release of OpenAPI 3.0. The members told ProgrammableWeb that while it's always possible the tentative release date for 3.0 could be pushed back due to comments submitted during the 2-week "last comment" period, it's highly unlikely. "We have been through three rounds of release candidates and feel that the specification is pretty well baked," said the team.

Once the final OpenAPI 3.0 specification is released, it is likely stakeholders will have to wait for support to show up in their favorite products (e.g. API management solutions, testing solutions, design tools, etc.). The team explained that "many of the OAI members are building products to support 3.0 so it shouldn't be nearly as long as it was for the 2.0 specification. But given the effort to build tooling and integrate with great big products, it makes sense for providers to hold back for a final specification." They also said that "folks from SmartBear, Microsoft, and Reprezen have all publicly announced in-progress tooling around OAS 3.0."

One of the key changes in the 3.0 specification is a new format to allow static linking between responses and future requests. "Statically-defined links are different from dynamically defined links. This feature was initially driven by the Bitbucket team at Atlassian to help reduce the size of payloads being returned from servers," the team explained. "When you know how to derive links in advance through a contract (i.e. via OAS document), the payloads can be smaller and more efficient, and tooling can know how to traverse links in a standardized manner."

When asked if the new linking format is specifically for defining hypermedia APIs (HATEOAS), the team said that "it is not an implementation of HATEOAS but solves many of the same things that HATEOAS tries to, and in (what the team feels) is a more efficient and elegant manner."

To learn more about the OAI and the OpenAPI 3.0 specification, visit OpenAPIs.org.

Janet Wagner is a technical writer and contributor to ProgrammableWeb who covers breaking news, in-depth analysis, and product reviews. She specializes in creating well-researched, in-depth content about APIs, machine learning, deep learning, computer vision, analytics, and other advanced technologies.

Comments