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.