OpenAPI 3.1 – Feeling afraid of hooks? This is what GEFEG.FX does better and this is what the newly released version offers!

The OpenAPI Initiative has just released version OpenAPI 3.1. On 17 February 2021, Ron Ratovsky from SmartBear and Darrel Miller from Microsoft presented the new version. This article deals with the question of what OpenAPI 3.1 brings with it that is new and what this means for existing implementations.

If you would like to know more about the OpenAPI specification standard itself, you are welcome to visit the official website or read the article “With OpenAPI, this is what your future looks like: A world without business documents. Think model-First with GEFEG.FX“.

The essential changes of OpenAPI 3.1

Support of webhooks

From my personal point of view, the most significant difference is the support of webhooks in APIs. Since the topic is new to many, I have written another small article on the topic “Still no catch on webhooks? Create your flexible APIs now with OpenAPI 3.1 and GEFEG.FX“. There you will also find an example. Webhooks are an essential factor for the success of WordPress. It is this technology that makes it possible to write applications efficiently and to extend them easily and in a standardised way via plug-ins. The OpenAPI initiative has also regarded webhooks as so essential that they are a new document type in OpenAPI. An OpenAPI specification now has three basic root elements: Paths, Components and Webhooks.

So now there can be a valid API specification that exclusively defines webhooks. At first glance, this may seem strange. But this can be something very useful. Applications are API-enabled more quickly, especially if they have a fixed process flow. It also means that existing APIs of applications like WordPress can now be specified cleanly.

When specifying a webhook, the path (endpoint) that is executed in the foreign API is defined. In contrast to a callback, a webhook is an active action in the foreign API. Write me in the comments what you think of the new webhooks.

While testing the webhooks, the need quickly arose to also make paths reusable, which leads to the next change.

Global path definitions

With version OpenAPI 3.1, paths can now also be specified under the components. Similar to the parameters, a globally available name can now be assigned to a path. This is an essential step towards standardisation and better governance of API implementations.

Referenced objects with overwritten description

Particularly when defining global objects or global data structures, one often comes to the situation that in the concrete application of the structure, the business term changes.

Here is a simple example: Let’s say we have defined a generic schema object with which we can map an address consisting of street, post office box, postcode, city and country. And now we want to use this address in different places. Even an organisation can have more than one address. From a purely postal point of view, an organisation in Germany can have a home address, a P.O. box address or a major customer address. If logistical considerations are then added, information on gates, branches or the like can be added, for example.

OpenAPI 3.1 now allows the summary and description to be overwritten when referencing a schema object. This means that these different forms of the address can now be clearly described.

What OpenAPI 3.1 cannot do, but the solution with GEFEG.FX

OpenAPI 3.1 only supports overwriting the verbal description of a reference. In particular, however, repetitions or (restrictive) changes to the referenced structure are not possible.

GEFEG.FX can do that. In the above example, it is not possible to distinguish between the structure of a home address, a P.O. box address and a major customer address. . In OpenAPI 3.1, this would require three different schema objects or the use of a OneOf structure. With GEFEG.FX, however, it can be defined directly at the reference that the major customer address, for example, consists only of postcode, city and country.

Support for roles and claims security

With version 3.1, roles are supported throughout the specification of security requirements. This simplifies rights management considerably. For example, it is now easy to define that write or delete operations require a different role than read access.

Description and summary

In addition to the description, there is now also a short summaryfor describing the objects of an API. The main difference is that the description supports Markdown formatting and is thus ideally suited for detailed descriptions for the developer. The summary on the other hand, does not support this. It serves as short information on the function of the object. Ideally, it can be used by code generation tools that generate source code directly from the OpenAPI 3.1 specification. The summary could be included in the source code as a comment, for example.

Full JSON schema support

The OpenAPI 3.0.x version forms both a subset of JSON Schema and a superset of JSON Schema. This has now been fixed. OpenAPI 3.1 is now fully compatible with JSON Schema.

Fewer format specifications for data types

OpenAPI 3.0.x defined a whole range of supported format specifications for data types. This changed with the OpenAPI 3.1 version. Some format specifications went beyond the JSON schema specification or repeated format specifications already defined there.

By approximating the JSON schema, only those formats are now specified that extend the JSON schema. At the same time, the specification of a format as a restriction of the data type has been removed. The specification of a format is now more of an annotation than a restriction. The check is therefore to be carried out by the respective application.

More changes with OpenAPI 3.1

In addition, there are a few more changes in OpenAPI 3.1, which I would like to summarise here:

• Multipart/form data support for parameters
• A path parameter must also be defined. This is actually logical, but was not explicitly required until now.
• All HTTP methods support request bodies. This also applies to DELETE, GET, POST.
• Responses are now optional. If a specification is developed in a “design-first” approach, it can make sense to specify it at a later stage. Especially in a collaborative environment, valid specifications can be exchanged that do not require fancy values for responses, as these may not yet be finally defined.
• When specifying media types, the contentEncoding can now also be specified.

I have linked the complete presentation of the OpenAPI 3.1 format below.

What does this mean for implementation?

When I look at the changes compared to the previous version, I can understand why the OpenAPI Initiative thought for a long time about whether it should be called OpenAPI 3.1 or rather OpenAPI 4.0.

On the other hand, most innovations are compatible. An API with a specification based on version 3.0.x still works. Only downward compatibility is no longer necessarily guaranteed. It is clear that the previous version did not yet know webhooks and global paths. But there would also be problems if the now optional responses were omitted. Such a specification would not have been a valid document in the previous version. But this constellation should occur in very few cases.