The OpenAPI Specification is a widely adopted specification for machine-readable API documentation. Previously part of the Swagger framework, OpenAPI became an independent project in 2016. In the last few years, the specification has undergone several significant updates — despite this, many users are still using older OpenAPI versions, especially OpenAPI v2.

Below, we’ll look at the most recent core revision, OpenAPI v3, and showcase some updates that have been made. We’ll examine why OpenAPI v3 is a robust specification solution and consider the benefits of updating to the current version.

OpenAPI Links

With OpenAPI v3, the Links feature was added. Links is precisely what it sounds like — a mechanism to describe relationships between responses and operations. Interestingly, this system does far more than describe these relationships; it also provides a way to define their interaction and traversal mechanism. In familiar terms, OpenAPI Links is akin to Hypermedia design. However, the key difference is that OpenAPI Links do not require the information to be present in the responses themselves.

Why This Matters

OpenAPI Links unlocks significant power for API developers. Links can be used for various functions like pagination or relationship mapping, but perhaps most powerful is the definition of how specific API URIs can be used to serve additional information. This unlocks a wide range of documentation, schema, specification, and other development paradigms, as navigation is now intrinsic to the system rather than externally defined and documented.

Document Structure Simplification

One of the most significant changes between OpenAPI v2 and v3 is the overall simplification of the document structure and its constituent parts. Several specific document structure definitions present in OpenAPI v2 have since been combined or replaced in OpenAPI v3, so much so that massive parts of the document structure have since shifted.

First of these is the combination of the hosts-specific elements host, basePath, and schemes into a singular hosts document structure. The same has occurred with the security and securityDefinitions structures, as these were combined into the security structures. It should also be noted that definitions, parameters, and responses have been combined into a general components structure, which contains all reusable objects, including headers and callbacks.

Why This Matters

This is a very important change to OpenAPI, as it makes for a much simpler document structure, thereby making it easier to write and reuse definitions. With a simpler structure, reusability is made much easier, and much of the complexity that once was a con when using OpenAPI v2 has been abstracted away. The document structure of OpenAPI was, for some, too complex in previous versions, leading to some confusion and commentary. Now that these elements have been simplified, it should be easier to build into the standard API stack in a recognizable and quickly digestible way.

Security Flow Changes

OpenAPI v3 predictably expanded its security schemes and bearer formats, but perhaps the most significant change for many users is not the new formats, but the changes in existing flows. As of OpenAPI v3, all HTTP security schemes are reflected as a new HTTP type, a change that simplified more complex presentations.

More notably, however, OAuth 2 flows, which were originally given names that matched OpenAPI specifications, have been renamed and restructured to reflect OAuth specific structures and naming approaches. For example, the application flow, which represented client-based application authorization, has been renamed to clientCredentials, which is more in line with OAuth’s actual flow name and documentation.

As part of this realignment and redefinition, a bevy of additional security features and flows were also added to OpenAPI v3. The addition of OpenID Connect Discovery as the openIdConnect type allows for authorization schemes that utilize metadata published by an authorization server, allowing for more flexible client application authentication.

Why This Matters

Firstly, alignment to OAuth should be mentioned as the major benefit that it is — open standards are only as good as the other standards they align with, so closer coupling in this way not only unlocks greater synchronicity, it simplifies the open solutions paradigm to greater success. The additional security flows now on offer with OpenAPI v3 are also a major benefit, as they create more methodologies for successful security practices, keeping pace with other security solutions currently in the industry.

Content Negotiation Support and Parameter Overhauls

As part of OpenAPI v3, there have been some major changes to parameter types. Firstly, the body and formData have been replaced by the requestBody parameter, a simplification that allows for a streamlined parameter type compared to the previous parameters.

OpenAPI v3 also adds a new parameter type called cookie, which can be utilized for APIs that use cookies. This is a significant change as cookie authentication was not supported in OpenAPI v2. Additionally, OpenAPI v3 issued expanded support for arrays and objects in operation parameters; these parameters can then be serialized using either the style or explode keywords.

OpenAPI3 also introduced a significant change in the definition of API requests and responses by way of the requestBody parameter. This parameter replaces the body and formData parameters and instead combines it into a single parameter that is more comprehensive and flexible. The new parameter supports the consumption of various media types, including JSON, XML, and other data and text formats.

Why This Matters

These changes have resulted in significantly improved interactions and controls. The most obvious of these changes has to do with the cookies parameter. Before OpenAPI3, workarounds were required to perform cookie authentication — these workarounds often went through header objects, complicating the interaction methodology at hand and making for complex API interactions. The changes to the request and response parameters, along with additional changes, including media type support in schemas and new form-data content types, unlock a significant amount of design choices and paradigms.

Improved Examples

OpenAPI has long included Examples, a set of descriptions that helps when generating mock APIs and improving documentation. In OpenAPI v2, however, these examples were limited to JSON and YAML objects, which limited a good deal of the extensibility and reusability of this feature. In OpenAPI v3, this has been expanded to support JSON strings and external examples, opening up a wide array of possibilities.

It should be noted that the entire example featureset itself was given an overhaul in OpenAPI v3, leading to greater extensibility and reusability. The ability to describe multiple examples allows for flexibility, especially when creating a mock API, and the option to reuse examples throughout the API removes the necessary duplicative work that was once common under OpenAPI v2.

Why This Matters

API development can be a very repetitive practice to be engaged in, and this largely comes from the nature of repeated objects, and methods, traversal systems. By overhauling the examples system within OpenAPI v3, this repetitiveness has been replaced with simplification. This simplification can result in much easier, quicker, and more comprehensive development efforts and could lead to significant gains in efficiency, both in terms of the total codebase, effort, and time.

JSON Schema Support Expansion

OpenAPI3 includes additional extended support for JSON Schema. In version 2, the support for JSON Schema keywords was relatively limited, which made for complex schema and workarounds. Under OpenAPI v3, additional schema keywords were added — notably, oneOf and anyOf. These keywords are important as they make for a much more flexible schema, and the definition of these alternative schemas leans heavily on the ability to leverage polymorphic pathways.

In essence, polymorphism is a design paradigm that allows objects to take different forms depending upon a set of criteria. These criteria are typically based on object inheritance or flow definition, and so the addition of these additional schema keywords unlocks this specific approach.

Why This Matters

It’s always beneficial when a security standard includes more support for additional paradigms and methodologies. That being said, the inclusion of JSON Schema is impactful from a development point of view. Enabling polymorphism in API development is very promising, and it allows for much greater flexibility and, therefore, extensibility and scalability than non-polymorphic solutions.

Callback Description Support

OpenAPI v3 added a significant new feature in its support for callbacks. Callbacks are an asynchronous approach to API communication, such as webhooks, and handle requests that a service sends to another service as an event response. Such a callback process would allow an API to wait for a specific event, such as a change on the backend resulting from a purchase, and then alert other APIs and subscribed entities to this change, providing data and information about the event as well as actions that can be taken in response. It’s important to note that these callback communications are “out-of-band,” routing through other connections than that which the user typically utilizes. In other words, this communication is not through the typical user flow but instead occurs outside this flow.

While this paradigm could, in theory, be enabled through third-party implementations or workarounds, OpenAPI v3 adds them as an object using the same path definition structures found elsewhere in OpenAPI. The new update also allows the definition and formatting of the subscription operation utilized to create these callback functions and the expected responses to those messages.

Why This Matters

The addition of the callback object is significant in enabling OpenAPI functionality and documentation around asynchronous APIs. This paradigm is extremely useful for many reasons, but the biggest benefit is the standardization around how this works and how to implement it. Without it being added into OpenAPI v3, anyone using OpenAPI would have to use workarounds or eschew the option altogether, which has long been a point of contention. With added support, a whole range of new API deployments can now leverage the solution.

Why Should You Upgrade?

The open question surrounding this new version is simple — why should any API upgrade to OpenAPI v3? The simple fact is that OpenAPI v2, while powerful and valuable, does not have support for some pretty core functions, such as making OpenAPI utilization possible for asynchronous APIs.

Even if your API does not utilize such asynchronous design, there’s enough in OpenAPI v3 to argue for adoption. Additional security schemas enable new development methodologies and approaches, the overhauled examples unlock reusable design and development, and expanded JSON support means easier to parse functions and responses.

More than anything else, however, OpenAPI v3 is stable and lossless. No data will be lost in the upgrade to OpenAPI v3, so the major hurdle to adopt — the fear of heavy process overhead in conversion to the updated standard — is really not that big a deal at all. The new features and processes included in OpenAPI v3 justify an update for all but the most specific use cases.

Conclusion

What do you think about OpenAPI3? Have we covered enough of the largest features? What do you think is the main value proposition to the modern web developer? Let us know in the comments below!