Was ist OpenAPI?

Eine OpenAPI-Datei, auch bekannt als OpenAPI-Dokument oder OpenAPI-Spezifikation, ermöglicht es Entwicklern, eine API zu beschreiben. Diese Spezifikation beschreibt auch die Verwendung dieser API, einschließlich der verfügbaren Endgeräte, Betriebsparameter, Authentifizierungsmethoden und weiterer Informationen. Sie wird entweder in YAML oder JSON verfasst, wobei das JSON-Schema zur Beschreibung der Datenformate innerhalb einer API verwendet wird.

OpenAPI dient sowohl als Dokumentation als auch als Vertrag (der im übertragenen Sinne beschreibt, was eine API leisten soll, jedoch nicht rechtsverbindlich ist) zwischen API-Konsumenten und -Herstellern. Es dient im Wesentlichen als „eine Quelle der Wahrheit“, die die Anweisungen in einem standardisierten Format bereitstellt.

Diese Standardisierung vereinfacht die API-Nutzung und Integration. Sie ermöglicht es sowohl Menschen als auch Computern, die Funktion und Struktur einer gegebenen API zu verstehen, ohne Zugriff auf den Quellcode zu haben oder die Funktionsweise der API im Detail verstehen zu müssen. Entwickler befähigt sie außerdem dazu, mit einer API zu arbeiten, unabhängig davon, in welcher Sprache sie geschrieben wurde.

OpenAPI automatisiert die interaktive, stets aktuelle Dokumentation, wodurch ein Teil der sich wiederholenden Dokumentationsarbeit entfällt und sichergestellt wird, dass die Dokumentation auf dem neuesten Stand bleibt. OpenAPI ermöglicht außerdem die Codegenerierung für Client-SDKs und die automatische Generierung weiterer Standardcodes aus der Spezifikation, wodurch menschliche Fehler reduziert und die Entwicklerarbeit weiter minimiert wird.

Tools, die OpenAPI-Spezifikationen verwenden, einschließlich SwaggerUI, können eine API-Spezifikation auf einer interaktiven Schnittstelle darstellen. Diese Schnittstelle hilft nicht nur bei der Visualisierung der Spezifikation, sondern ermöglicht auch echte API-Aufrufe direkt vom Browser oder Webservice aus, zu Test- und Validierungszwecken.

Durch die Standardisierung der Beschreibung von REST-APIs trägt OpenAPI zur Verbesserung der Interoperabilität und des Toolings bei und unterstützt den Betrieb während des gesamten API-Lebenszyklus. Eine starke, effektiv gewartete Spezifikation kann als grundlegendes Hilfsmittel für die Umsetzung einer umfassenden API-Strategie dienen, das Integration, Zusammenarbeit, Fehlervermeidung und ein stärkeres API-Management unterstützt.

Die vollständige Spezifikation finden Sie auf GitHub.

Als de-facto-Branchenstandard bietet OpenAPI ein sicheres, automatisiertes und weithin verständliches Dokument für die API-Entwicklung.

OpenAPI wurde ursprünglich von dem Entwickler Tony Tam ins Leben gerufen und erstmals 2011 unter dem Namen Swagger veröffentlicht. Damals waren API-Spezifikationen oft statische Dokumente, die mühsam aktualisiert werden mussten und häufig veraltet waren. Die Swagger-Spezifikation enthielt mehrere Innovationen in der API-Entwicklung, darunter eine Schaltfläche zum „Ausprobieren“, um API-Aufrufe live und in Echtzeit zu testen.

Swagger machte die Dokumentation zu einem Schwerpunkt seiner Existenz. Es ermöglichte Entwicklern das Einfügen von Anmerkungen, ähnlich wie Haftnotizen, in ihren Quellcode. Swagger konnte diese Anmerkungen lesen und die Dokumentation automatisch aktualisieren, um sicherzustellen, dass sie ohne mühsame und sich wiederholende Aktualisierungen auf dem neuesten Stand blieb. Swagger führte außerdem ein Format zur Beschreibung von APIs in maschinenlesbarem JSON ein, was es sprachunabhängig machte: Unabhängig von der Sprache eines Backends gab Swagger eine universelle JSON-Datei aus.

Swagger wurde 2015 von SmartBear Software übernommen, kurz darauf in OpenAPI umbenannt und der neuen OpenAPI Initiative (OAI) unter dem Dach der Linux Foundation gespendet. Die aktuelle Version ist OpenAPI 3.1.

Die OpenAPI-Spezifikation ist ein standardisiertes, für Mensch und Maschine lesbares Dokument, das die API-Struktur und -Syntax definiert. Alle OpenAPI-Dokumente enthalten bestimmte Komponenten und entsprechen der gleichen Grundstruktur, wobei einige Spezifikationen mehr Informationen als andere enthalten. Eine Spezifikation muss mindestens openAPI enthalten und info Felder und mindestens ein path , component oder webhook Feld. ¹

OpenAPI: Vermerkt die OpenAPI-Version, die das Dokument verwendet, wie „3.1.1“

Info: Beinhaltet allgemeine API-Metadaten, wie den API-Titel und die Versionsnummer, eine Beschreibung der API, Nutzungsbedingungen und Kontaktinformationen. 

Server: Eine Liste von Basis-URLs, über welche auf die API zugegriffen werden kann (kann sowohl Staging- als auch Produktionsumgebungen umfassen). Diese Liste enthält Variablen für umgebungsspezifische Hosts.

Pfade: Beschreibt die Pfade und die zugehörigen HTTP-Methoden (oder Operationen, zum Beispiel GET, PUT, POST) und die Parameter, Anfragetexte und Antworten für jedes Pfadelement.

Komponenten: Listet wiederverwendbare Objekte wie Datenschemata, Parameter, Antworten, Überschriften und Sicherheitsdefinitionen auf. Diese Objekte können im gesamten Dokument referenziert werden. Komponenten werden ganz einfach mit $ref referenziert. Diese Strategie sorgt für ein möglichst effektives API-Design. 

Sicherheit: Gibt die Sicherheitsschemata und Authentifizierungsmechanismen an, die die API verwendet, wie zum Beispiel OAuth oder API-Schlüssel. Ermöglicht auch die Anwendung von Sicherheitsschemata auf globaler Ebene oder pro Vorgang.

Tags: Übergeordnete Liste von Tags, die zur Organisation von Vorgängen verwendet werden. Die Verwendung von Tags kann die Verständlichkeit von Dokumenten verbessern (z. B. „Benutzer“ oder „Bestellungen“).

Externe Dokumentation: Links zu Leitfäden, Onboarding-Dokumenten und anderen externen Dokumenten für die API

Webhooks: Beschreibt eingehende Aufrufe, die die API empfängt. 

OpenAPI bietet eine Single-Source-of-Truth (SSOT) für API-Entwickler und -Benutzer und stellt Funktionen bereit, die API-Projekten Mehrwert und Effizienz verleihen.

OpenAPI wurde ursprünglich mit einem starken Fokus auf die Dokumentation von REST-APIs entwickelt, und dieser Fokus steht auch heute noch im Mittelpunkt. Die Dokumentation ist standardisiert, interaktiv, wird in Echtzeit aktualisiert und bietet einen Vertrag mit einer Single-Source-of-Truth.

Es gibt verschiedene Tools zum Lesen von OpenAPI-Dokumenten und zum Exportieren von Code. Eines dieser Tools ist Swagger Codegen, das Dokumente liest, die gemäß der OpenAPI-Spezifikation geschrieben wurden. Swagger Codegen kann dann API-Client-Code-Software Development Kits (SDKs), serverseitigen Code (Stubs) und lesbare Webseiten mit aktueller, für Menschen verständlicher Dokumentation erzeugen.

Eine der innovativsten Funktionen von OpenAPI ist nach wie vor die Schaltfläche „Ausprobieren“, die Tests und Validierungen in Echtzeit direkt im Browser ermöglicht. Die Swagger-Benutzeroberfläche, ein kostenloses Open-Source-Tool, stellt eine visuelle Oberfläche dar, auf der Entwickler tatsächliche Anfragen senden können, um sicherzustellen, dass eine gewünschte Reaktion erfolgt. Dieses Tool erleichtert die sofortige Überprüfung, ob eine Anfrage funktioniert.

OpenAPI wird häufig zusammen mit Integrationsplattformen als Service oder iPaaS verwendet.

iPaaS-Plattformen nutzen OpenAPI-Spezifikationen, um verschiedene Anwendungen in einem IT-Ökosystem zu verstehen und zu verbinden. Wenn Anwendungen OpenAPI-Spezifikationen bereitstellen, die ihre APIs beschreiben, können iPaaS-Plattformen diese Informationen nutzen, um automatisch Endgeräte, Authentifizierungsmethoden und Datenstrukturen zu entdecken. Diese Strategie beschleunigt den Aufbau von Integrationen, wie z. B. die Verbindung einer E-Commerce-Plattform mit einer Buchhaltungssoftware.

OpenAPI ermöglicht es Frontend- und Backend-Entwicklern außerdem, parallel zu arbeiten. Paralleles Arbeiten ist besser, als wenn, wie es manchmal der Fall ist, das Frontend-Team warten muss, bis das Backend-Team seine Datenbank zum Laufen gebracht hat. Mit einem OpenAPI-Vertrag kann das Frontend-Team einen simulierten API-Server erstellen, der sich wie ein echter verhält, wodurch Tests ermöglicht und optimiert werden können, bevor die Backend-Entwicklung abgeschlossen ist. 

API-Governance – die Standards, Richtlinien und Praktiken, die bestimmen, wie ein Unternehmen APIs entwickelt und nutzt – ist entscheidend, um sicherzustellen, dass APIs nahtlos, konstant und ohne unnötige Wiederholungen funktionieren. Da OpenAPI als Vertrag zwischen Entwicklern fungiert, können Governance und Sicherheit von Anfang an integriert werden.

Nehmen wir beispielsweise API-Gateways, die Aufgaben wie Traffic-Routing, Überwachung und Ratenbegrenzung übernehmen. API-Gateways können in der Regel OpenAPI-Spezifikationen verarbeiten und alle in der Spezifikation festgelegten Verkehrsbeschränkungen oder andere Sicherheitsmaßnahmen durchsetzen.

Das Gleiche gilt für Sicherheitsregeln. Eine OpenAPI-Spezifikation ermöglicht es Entwicklern, Sicherheitsanforderungen (wie die Verwendung von OAuth 2.0 und API-Schlüsseln) zu deklarieren, und diese Anforderungen können nachgelagert (beispielsweise durch ein Gateway) durchgesetzt werden.  Die Beschreibung von Sicherheitsmerkmalen in einem API-Vertrag hilft sicherzustellen, dass Entwickler keine nicht unterstützten Sicherheitsschemata einführen.

OpenAPI kann das API Management, den skalierbar Prozess der Erstellung, Veröffentlichung und Verwaltung von API-Verbindungen, auf verschiedene Weise stärken. Da die OpenAPI-Spezifikationen maschinenlesbar und standardisiert sind, kann Katalog- und Portalsoftware sie beispielsweise automatisch indizieren. Durch diese Standardisierung sind APIs innerhalb eines Unternehmens leichter zu finden und zu verstehen. Diese Auffindbarkeit verhindert, dass Teams unwissentlich doppelte APIs entwickeln.

OpenAPI unterstützt zudem ein einheitliches Management und eine konstante Governance, indem es Unternehmensstandards explizit und durchsetzbar gestaltet. Teams können Anforderungen, wie z.B. Versionskonventionen, Fehlerantwortformate oder Benennungsmuster, direkt in oder neben der Spezifikation definieren. Da diese Erwartungen in einem standardisierten Format dokumentiert sind, können sie beim Hinzufügen neuer APIs automatisch validiert werden. Diese Validierung verringert die Abhängigkeit von manuellen Überprüfungen und trägt dazu bei, dass APIs auch dann konstant bleiben, wenn das Portfolio eines Unternehmens wächst.