OpenAPI 3.1 – Angst vor Haken? Das macht GEFEG.FX besser und das bringt die gerade veröffentlichte Version!

Die OpenAPI Initiative hat gerade die Version OpenAPI 3.1 veröffentlicht. Am 17.02.2021 stellten Ron Ratovsky von SmartBear und Darrel Miller von Microsoft die neue Version vor. Dieser Artikel beschäftigt sich mit der Frage, was OpenAPI 3.1 Neues mit sich bringt und was das für bestehende Umsetzungen bedeutet.

Wer mehr zum Spezifikationsstandard OpenAPI an sich erfahren möchte, kann gerne auf der offiziellen Webseite oder in dem Artikel “Mit OpenAPI sieht so für mich die Zukunft aus: Eine Welt ohne Geschäftsdokumente. Model-First mit GEFEG.FX” nachlesen.

Die wesentlichen Änderungen von OpenAPI 3.1

Unterstützung von Webhooks

Aus meiner persönlichen Sicht ist der größte Unterschied die Unterstützung von Webhooks in APIs. Da das Thema für viele neu ist, habe ich noch einen kleinen Artikel zum Thema “Kein Haken an Webhooks. Jetzt flexible APIs bauen mit OpenAPI 3.1 und GEFEG.FX” verfasst. Dort findet sich auch ein Beispiel. Webhooks sind ein wesentlicher Erfolgsfaktor von WordPress. Erst diese Technik ermöglicht es Anwendungen effizient zu schreiben, und sie über Plug-ins einfach und standardisiert zu erweitern. Auch die OpenAPI Initiative hat Webhooks als so wesentlich angesehen, dass sie ein neuer Dokumententyp in OpenAPI sind. Eine OpenAPI Spezifikation hat somit nun drei grundlegende Wurzelelemente: Paths, Components und Webhooks.

Es kann nun also eine gültige API-Spezifikation geben, die ausschließlich Webhooks definiert. Auf den ersten Blick mag das seltsam erscheinen. Doch das kann etwas sehr Nützliches sein. Anwendungen sind schneller API-fähig, insbesondere, wenn sie einen festen Prozessablauf haben. Auch können damit nun bestehende APIs von Anwendungen wie WordPress sauber spezifiziert werden.

Bei der Spezifikation eines Webhooks wird der Pfad (Endpunkt) definiert, der in der fremden API ausgeführt wird. Im Gegensatz zu einem Callback ist ein Webhook also eine aktive Aktion in der fremden API. Schreibt mir doch mal in die Kommentare, was Ihr von den neuen Webhooks haltet.

Im Rahmen der Erprobung der Webhooks ergab sich schnell der Bedarf, auch Pfade wiederverwendbar zu machen, was zu der nächsten Änderung führt.

Globale Pfaddefinitionen

Mit der Version OpenAPI 3.1 können nun auch Pfade unter den Components spezifiziert werden. Ähnlich wie bei den Parametern kann einem Pfad nun ein global verfügbarer Name zugeordnet werden. Dies ist ein wesentlicher Schritt zur Standardisierung und besserer Governance von API – Implementationen.

Referenzierte Objekte mit überschriebener Beschreibung

Gerade bei der Definition globaler Objekte oder globaler Datenstrukturen kommt man häufig zu der Situation, dass in der konkreten Anwendung der Struktur sich der betriebswirtschaftliche Begriff ändert.

Hierzu ein einfaches Beispiel: Sagen wir mal, wir haben ein generisches Schema-Objekt definiert, mit der wir eine Anschrift bestehend aus Straße, Postfach, Postleitzahl, Ort und Land abbilden können. Und nun wollen wir diese Anschrift an verschiedenen Stellen nutzen. Bereits bei einer Organisation kann es aber mehr als eine Anschrift geben. Aus rein postalischer Sicht kann eine Organisation in Deutschland eine Hausanschrift, eine Postfachanschrift oder eine Großkundenanschrift haben. Kommen dann noch logistische Überlegungen hinzu, so können zum Beispiel noch Informationen zu Toren, Filialen oder ähnlichem hinzukommen.

OpenAPI 3.1 erlaubt nun bei der Referenz auf ein Schemaobjekt, die Summary und die Description zu überschreiben. Somit können nun also diese verschiedenen Ausprägungen der Anschrift klar beschrieben werden.

Was OpenAPI 3.1 nicht kann, aber die Lösung mit GEFEG.FX

OpenAPI 3.1 unterstützt lediglich das Überschreiben der verbalen Beschreibung einer Referenz. Insbesondere Wiederholhäufigkeiten oder (einschränkende) Änderungen an der referenzierten Struktur sind jedoch nicht möglich.

GEFEG.FX kann das. So ist es im obigen Beispiel nicht möglich, die Struktur einer Haus-, Postfach- und Großkundenanschrift zu unterscheiden. In OpenAPI 3.1 wären dafür drei verschiedene Schemaobjekte bzw. die Verwendung einer OneOf – Struktur erforderlich. Mit GEFEG.FX kann jedoch direkt an der Referenz definiert werden, dass die Großkundenanschrift zum Beispiel nur aus Postleitzahl, Ort und Land besteht.

Unterstützung von Rollen und Claims Security

Mit der Version 3.1 werden durchgängig Rollen bei der Spezifikation von security requirements unterstützt. Das vereinfacht die Rechteverwaltung wesentlich. So kann nun zum Beispiel einfach definiert werden, dass schreibende oder löschende Operationen eine andere Rolle benötigen, als der lesende Zugriff.

Description und neue Summaries

Zur Beschreibung von Objekten eines APIs existieren nun neben der description auch noch eine kurze summary. Der wesentliche Unterschied besteht darin, dass die description eine Markdown-Formatierung unterstützt und somit für ausführliche Beschreibungen für den Entwickler ideal geeignet ist. Die summary unterstützt dies hingegen nicht. Sie dient als kurze Zusammenfassung der Funktion des Objektes. Idealerweise kann es somit von Code-Generation-Tools verwendet werden, die Sourcecode direkt aus der OpenAPI 3.1 Spezifikation erzeugen. Die summary könnte zum Beispiel als Kommentar in den Quellcode übernommen werden.

Volle Unterstützung von JSON Schema

Die Version OpenAPI 3.0.x bildet sowohl eine Untermenge von JSON Schema, als auch eine Obermenge von JSON Schema. Das wurde nun behoben. OpenAPI 3.1 ist nun vollständig kompatibel mit JSON Schema.

Weniger Formatangaben bei Datentypen

OpenAPI 3.0.x hat eine ganze Reihe unterstützter Formatangaben bei Datentypen definiert. Das hat sich mit der Version OpenAPI 3.1 geändert. Die Formatangaben gingen teilweise über die JSON Schema Spezifikation hinaus bzw. wiederholten bereits dort definierte Formatangaben.

Durch die Annäherung an JSON Schema werden nun nur noch diejenigen Formate spezifiziert, die das JSON Schema erweitern. Gleichzeitig wurde die Angabe eines Formates als Einschränkung des Datentyps aufgehoben. Die Angabe eines Formates ist nun also mehr eine Annotation, als eine Einschränkung. Die Prüfung ist also durch die jeweilige Applikation vorzunehmen.

Weitere Änderungen mit OpenAPI 3.1

Darüber hinaus gibt es noch ein paar weitere Änderungen in OpenAPI 3.1, die ich hier nur stichpunktartig zusammenfassen möchte:

• Unterstützung von Multipart/form data für Parameter
• Ein Path-Parameter muss auch definiert sein. Dies ist eigentlich logisch, war bisher aber nicht explizit vorgeschrieben.
• Alle HTTP Methoden unterstützen Request Bodies. Also auch bei DELETE, GET, POST.
• Dafür sind nun aber Responses optional. Wird eine Spezifikation in einem “Design-First” Ansatz entwickelt kann es sinnvoll sein, diese erst zu einem späteren Zeitpunkt zu spezifizieren. Gerade in einer kollaborativen Umgebung können somit gültige Spezifikationen ausgetauscht werden, die keine Fantasiewerte für Responses benötigen, da diese vielleicht noch nicht endgültig festgelegt sind.
• Bei der Angabe von Mediatypes kann nun auch das contentEncoding angegeben werden.

Die vollständige Vorstellung des OpenAPI 3.1 Formats (in englischer Sprache) habe ich Euch einmal hier verlinkt.

Was bedeutet das für die Umsetzung?

Wenn ich mir die Änderungen im Vergleich zur Vorgängerversion anschaue, kann ich schon verstehen, warum die OpenAPI Initiative lange darüber nachgedacht hat, ob es OpenAPI 3.1 oder nicht doch lieber OpenAPI 4.0 heißen soll.

Auf der anderen Seite sind doch die meisten Neuerungen kompatibel. Eine API mit einer Spezifikation auf Basis von Version 3.0.x, funktioniert weiterhin. Lediglich die Abwärtskompatibilität ist nicht mehr unbedingt gewährleistet. Das die Vorgängerversion noch keine Webhooks und globale Pfade kannte, ist klar. Probleme würde es aber auch geben, wenn die nun optionalen Responses weggelassen würden. Eine solche Spezifikation wäre in der Vorgängerversion kein gültiges Dokument gewesen. Doch diese Konstellation sollte in den wenigsten Fällen auftreten.