OpenAPI: Ein Standard – viele Möglichkeiten

Gut dokumentierte Programmierschnittstellen (häufig nur API, engl. für Application Programming Interface, genannt) sind Voraussetzung, um Programme oder Anwendungen entwickeln zu können. Gleiches gilt für Anwendungen, die bspw. über einen Webbrowser aufgerufen und genutzt werden.  In diesem BloQ-Artikel möchten wir einen Standard zur Beschreibung von APIs genauer beleuchten: die OpenAPI-Spezifikation.

Damit Unternehmen effizient wirtschaften können, müssen nicht nur die Mitarbeiter:innen und Abteilungen gut zusammen funktionieren. In den meisten Fällen nutzen Organisationen eine Vielzahl von unterschiedlichen Softwarelösungen, mit deren Hilfe sie die eigenen Prozesse optimal abbilden. Grundsätzlich ist dieser Ansatz sehr sinnvoll, schließlich möchte man stets die beste, spezialisierte Software für den jeweiligen Fachbereich nutzen. Klar ist aber auch, dass diese Softwarelösungen miteinander harmonieren müssen, damit ein einheitlicher Datenbestand ohne Redundanzen sowie einwandfreie Prozesse gewährleistet werden können. Auch in der Qualitätswelt werden Unternehmen nicht selten mit dieser Herausforderung konfrontiert. Es ist dann Aufgabe des Softwareanbieters, eine Anbindung an Unternehmenssoftware in Form einer Datenschnittstelle sicherzustellen.

Derartige Datenschnittstellen sind jedoch nicht mit Programmierschnittstellen (API) zu verwechseln, um die es in diesem BloQ-Artikel gehen soll. Entwickler:innen von Softwareprogrammen- und -anwendungen sind auf eben diese APIs angewiesen, die von Softwaresystemen zur Verfügung gestellt werden. Doch da endet der Wirkungsbereich längst nicht: Wir alle treffen in unserem Alltag auf solche Programmierschnittstellen – ohne, dass uns diese unmittelbar bewusst werden. Wenn wir etwa mit unserem Rechner arbeiten und Informationen abrufen oder Funktionen ausführen möchten, gewährleisten APIs, dass das System unsere Anforderung versteht und erfüllt. Sie fungieren im Grunde als Vermittler zwischen uns, den Nutzer:innen, und den von uns benötigten Informationen.

APIs kommen demnach in sehr vielen Anwendungsszenarien zum Einsatz; bewegen wir uns dabei im Webumfeld, etwa auf Online-Shops, werden sie in Form von sogenannten Web-APIs genutzt. Anwendungsbeispiele von Web-APIs sind etwa die Einbindung unterschiedlicher Bezahlmöglichkeiten, Bewertungssysteme oder weiterer Services. Doch welche Rolle spielt nun die OpenAPI-Spezifikation?

„Die OpenAPI-Spezifikation (OAS) definiert eine standardisierte, programmiersprachenunabhängige Schnittstellenbeschreibung für HTTP-APIs, die es sowohl Menschen als auch Computern ermöglicht, die Fähigkeiten eines Dienstes zu erkennen und zu verstehen […]. Ähnlich wie die Schnittstellenbeschreibungen die Programmierung auf niedrigerer Ebene erleichtert haben, beseitigt die OpenAPI-Spezifikation das Rätselraten beim Aufrufen eines Dienstes.“ (Zur OpenAPI-Spezifikation v. 3.1.0) Was in diesem Zitat erstmal recht kompliziert beschrieben wird, soll genau das Gegenteil bewirken: Die OpenAPI-Spezifikation liefert einen Standard, ein offenes und herstellerneutrales Beschreibungsformat, durch das (insbesondere REST-konforme, dazu später mehr) APIs beschrieben, getestet und dokumentiert werden können.

Kurzer Schlenker zur Geschichte: Die OpenAPI-Spezifikation war einst Teil des Softwareprojekts Swagger, wurde dann aber im Jahr 2016 ein eigenständiges Projekt, verwaltet von der OpenAPI Initiative. Namhafte Unternehmen wie Google, Microsoft und SAP sind Mitglieder der Initiative. Mittlerweile befindet sich der Standard in der Version 3.1.0.

Eine Herausforderung bei der Entwicklung einer API ist es häufig, die Implementierung, Dokumentation sowie Prüfung unter einen Hut zu bekommen – ohne längere Bearbeitungszeiten in Kauf nehmen zu müssen. OpenAPI erlaubt es hier, eine Programmierschnittstelle auf eine einheitliche Weise zu beschreiben. Das schafft unter anderem eine effizientere Zusammenarbeit zwischen Backend- und Frontend-Entwickler:innen, die unabhängig voneinander APIs entwickeln, implementieren und testen können, da von beiden Teams Code-Komponenten erstellt werden.

Hinzukommt, dass die Entwicklung sowie die Dokumentation einer API grundsätzlich nicht gerade banal ist. Durch den gemeinsamen Standard, den die OpenAPI-Spezifikation bietet, werden Prozesse deutlich vereinfacht. Das liegt nicht zuletzt daran, dass sowohl die Dokumentation der Schnittstelle als auch die Verbreitung dieser ohne gemeinsame Programmiersprache wesentlich unkomplizierter erfolgen können.

Der OpenAPI-Standard legt die Struktur für verschiedene Objekte fest. Diese Objekte (zum Beispiel Info Object, Paths Object oder Server Object) stellen eine Zusammenfassung der Eigenschaften dar, die für den Aufbau einer API genutzt werden können. In der Praxis wird OpenAPI dann vor allem zur Beschreibung von REST-APIs (aus dem Englischen: Representational State Transfer) verwendet. Durch Programmierschnittstellen nach dem REST-Schema bekommen Entwickler:innen schnell und leicht Zugriff auf Daten, bspw. zum aktuellen Wetter oder zur Verkehrslage, die sie in die eigene Anwendung implementieren können. Die strukturierten Daten sind leichter zu verarbeiten, allerdings benötigt man eine Dokumentation, aus der hervorgeht, wie die Endpunkte heißen und welche Daten sie liefern. Durch die OpenAPI-Spezifikation erhalten Entwickler:innen eine standardisierte Basis für REST-APIs, was nicht nur die Entwicklung vereinfacht, sondern auch den Implementierungsaufwand minimiert. Bei der API-Definition werden in erster Linie die beiden Datenformate JSON und YAML verwendet.

OpenAPI hat sich in den letzten Jahren dank der vielen genannten Vorteile als Beschreibungsstandard für Programmierschnittstellen etabliert und wird flächendeckend verwendet. Kein Wunder, denn für Unternehmen, die eigene Anwendungen entwickeln, als auch für solche, die diese Anwendungen dank OpenAPI problemlos weiterverwenden können, stellt die Spezifikation eine Win-Win-Situation dar.