OpenAPI: Der Schlüssel zur modernen API-Welt

In der Zeit von Microservice-Architektur und Software-as-a-Service sind APIs aus der Softwareentwicklung nicht mehr wegzudenken. Die unterschiedlichsten Anwendungen oder Services kommunizieren miteinander, häufig auch über die Unternehmensgrenze hinaus. In dieser komplexen Welt gibt es natürlich verschiedene Technologien und Begriffe, die auch manchmal miteinander verwechselt werden. Die meisten, die sich mit APIs auseinandergesetzt haben, werden wahrscheinlich auch schon mal die Begriffe Swagger oder OpenAPI gehört haben. Dieser Blog-Artikel soll euch OpenAPI näherbringen und euch zeigen, dass die einheitliche Dokumentation von APIs nur ein kleiner Bruchteil der Vorteile ist.

Was ist OpenAPI?

Beginnen wir mit der Historie von OpenAPI für den Fall, dass man mal bei „Wer wird Millionär“ sitzt. Die OpenAPI Spezifikation (kurz OAS) ist ein programmiersprachenunabhängiger Standard zur Beschreibung von HTTP-Programmierschnittstellen, wie REST-APIs. Die Geschichte von OpenAPI begann ursprünglich unter dem Namen Swagger, welches 2010 von Tony Tam entwickelt und schnell populär wurde, da es Entwicklungsteams ermöglichte, ihre APIs in einem standardisierten Format zu beschreiben und zu dokumentieren. Im Jahr 2015 wurde das Projekt an die OpenAPI Initiative (OAI) übergeben, die von der Linux Foundation gegründet wurde. Das Ziel der OAI war es, die Entwicklung und Verbreitung der Spezifikation weiter voranzutreiben – mit Erfolg, denn OpenAPI ist heute der De-facto-Standard für die Beschreibung von RESTful-APIs. Aber was ist OpenAPI jetzt eigentlich genau?

OpenAPI ist letztlich eine Spezifikation, welche mit einer vorgegebenen Syntax, die Möglichkeit schafft, REST-API-Interfaces einheitlich zu beschreiben. Dazu muss eine OpenAPI Definition erstellt werden, welche in einer YAML- oder JSON-Datei gespeichert wird. In dieser Definition wird der Service und dessen Funktionalität beschrieben, sodass sowohl Menschen als auch Maschinen die Spezifikation des Services lesen können.

Beschreibung des REST Webservice für den Witz des Tages

Damit das ein wenig greifbarer wird, stellen wir uns vor, dass wir einen REST Webservice entwickelt haben, bei dem Entwicklungsteams jeden Morgen den Witz des Tages abrufen können. Der Service ist unter der URL https://api.fabiens-flachwitze.de/v1 erreichbar. Die einzige Funktion des Service ist die HTTP-Method GET auf den Endpunkt /joke-of-the-day mit dem man den tagesaktuellen Flachwitz aufrufen kann. Damit andere Entwicklungsteams nun die Witze in ihrer App, zum Beispiel in einer d.velop cloud App auf dem Dashboard anzeigen können, sollten wir nun den Webservice beschreiben. Dies machen wir in einer OpenAPI Definition als YAML-File. Das könnte zum Beispiel so aussehen:

Nutzung der OpenAPI Spezifikation zur automatischen Generierung von Dokumentationen und Client-SDKs

Diese API-Beschreibung ist nun für euch lesbar. Ihr seht, dass es sich um eine OpenAPI Definition der Version 3.1.1. handelt (Zu den Versionen der OpenAPI Spezifikationen). Darunter seht ihr ein paar allgemeine Informationen zu dem Webservice, aber auch unter welcher URL das Ganze erreichbar ist. Unter dem Bereich “paths” werden die Endpunkte aufgelistet, in diesem Fall gibt es nur den einen Pfad und auch nur eine HTTP-Methode. Im Erfolgsfall bekommt ihr eine 200 Response zurück mit einem Beispiel-Witz oder wenn was schiefgelaufen ist einen Fehler mit dem Statuscode 500. Da wir alle lachen wollen, haben wir die Authentifizierung bewusst weggelassen.

Aber wenn wir jetzt mal ehrlich sind, so richtig schön ist das bisher nicht. Genau hier können wir uns jetzt das volle Potenzial von OpenAPI zunutze machen, denn die Beschreibung kann, wie bereits erwähnt, auch von weiteren Tools gelesen werden. Diese ermöglicht es nun, dass wir uns automatisch eine Dokumentation oder aber auch ein Client-SDK generieren lassen können.

Als Beispiel könnte man hier Scalar verwenden, welches automatisch eine interaktive Dokumentation erstellt, die auch noch Beispiele in den unterschiedlichsten Programmiersprachen bereitstellt, wie meine API verwendet werden kann.

Aber was ist nun eigentlich Swagger?

Ihr fragt euch bestimmt, warum wir in dem Beispiel gerade Scalar verwendet haben. Wir wollten euch zeigen, dass es noch viele andere Tools gibt, die mit OpenAPI arbeiten. Denn Swagger ist eigentlich eine Sammlung von Open-Source-Tools, die ebenfalls die OpenAPI Spezifikationen verwenden. Swagger hat zwar ursprünglich mal die Spezifikation entwickelt, diese wurde aber zu OpenAPI umbenannt und unter Swagger findet man nun die Tools, wie beispielsweise dem Swagger Editor, Swagger Codegen oder Swagger UI, das wahrscheinlich viele kennen und welches irrtümlicherweise immer als „das ist doch mit OpenAPI gemeint“ verwechselt wird.

OpenAPI bei der d.velop

Die d.velop ist klassisch mit dem Angebot von Software für On-Premises-Systeme groß geworden und es gab stets die Möglichkeit, die Software individuell durch Hooks oder Skripting, zunächst über JPL und später auch über Groovy-Programmierung, anzupassen. In dieser Zeit gab es keine oder kaum RESTful APIs und die Dokumentationen waren dementsprechend sehr unterschiedlich. Mit der Einführung von Microservices standen wir vor neuen Herausforderungen, denn zu Beginn gab es keine spezifischen API-Guidelines oder sie waren sehr allgemein formuliert. Dadurch hat jedes Team seine APIs nach eigenem Ermessen beschrieben. Dies führte dazu, dass der Aufbau der Dokumentationen von Service zu Service komplett unterschiedlich war.

Unser erreichte über die Zeit immer wieder das Feedback unserer Partner, dass unsere API-Dokumentationen unübersichtlich sind und jede Entwicklungs-Doku anders aufgebaut ist. Als SaaS- und Plattformanbieter wurde uns bewusst, dass wir den Missstand der chaotischen API-Dokumentationen beheben mussten, um unseren Partnern eine effizientere Entwicklung zu ermöglichen. Da wir das Rad nicht neu erfinden wollten, haben wir eine Initiative ins Leben gerufen, dass wir uns an den De-Facto-Branchen-Standard halten wollen und jedes Team ihre APIs als OpenAPI Definition anliefern muss.

Die flächendeckende Umstellung aller Public APIs erwies sich jedoch als größere Aufgabe, als wir uns das vorgestellt hatten. Eine der größten Herausforderungen war der Umfang der Arbeit, die mit der Umstellung verbunden war, da wir bei der d.velop mittlerweile eine Vielzahl an Services haben. Wir mussten also erst einmal katalogisieren, welche unserer Services eine Public-API besitzen. Glücklicherweise wurde die Initiative positiv aufgenommen, und die Entwicklungsteams wurden bei der Umsetzung von unseren Consultingteams unterstützt. Die bereichsübergreifende Zusammenarbeit zeigt, dass das Thema relevant und wichtig für unser Unternehmen ist.

Fazit

Wir sind große Fans von OpenAPI und sind froh, dass wir nun mit der Einführung einen großen Schritt in die Zukunft gemacht haben. Den ersten Erfolg können wir bereits verzeichnen und lösen mit der Generierung der API-Dokumentationen das Problem der Unübersichtlichkeit durch die Vereinheitlichung. Man findet sich jetzt schneller zurecht und die Interaktivität der Dokumentationen hilft, die Funktionen schneller zu verstehen. In unseren Teams gewinnen wir dadurch aber on-top noch Zeit, die wir für die Weiterentwicklung nutzen können, da die Dokus jetzt nicht mehr manuell geschrieben werden müssen.

Dies ist aber auch nur der Anfang, denn dieser Schritt ermöglicht es uns in Zukunft, für unsere Anwendungen auch SDKs (Clientcode) für euch zur Verfügung zu stellen, um euch die Entwicklung in euren Projekten zu vereinfachen. Auch ermöglichen uns Tools mit Low-Code-Ansätzen Integrationen in andere Plattformen. Darüber hinaus können wir OpenAPI auch dazu nutzen, automatisierte Security-Scans oder Quellcode-Analysen durchzuführen, um unsere Qualität der Services weiter zu verbessern.

OpenAPI ist also nicht nur eine Lösung für aktuelle Herausforderungen, sondern auch ein wichtiger Baustein für unsere zukünftige Entwicklung. Wir sind überzeugt, dass dieser Schritt uns und unseren Partnern helfen wird, schneller und effektiver auf Marktanforderungen zu reagieren und innovative Lösungen zu entwickeln.

Schau gerne mal bei unserem Developer-Portal vorbei, dort findest du bereits jetzt schon einen Großteil unserer API-Dokus im OpenAPI Format.