Kurze Zeitreise

Wie bereits zu Beginn erwähnt, geht die Entstehung von OpenAPI auf die Einführung der Swagger-Spezifikation zurück, die ursprünglich Tony Tam im Jahr 2010 entwickelt hat. Swagger entstand aus dem Bedürfnis heraus, eine standardisierte und einfache Möglichkeit zur Beschreibung, Dokumentation und Interaktion mit RESTful-APIs zu schaffen. Die Spezifikation und die damit verbundenen Tools gewannen schnell an Popularität in der Entwicklergemeinschaft.

Im Jahr 2015 wurde die OpenAPI-Initiative (OAI) ins Leben gerufen, um die Weiterentwicklung der Swagger-Spezifikation in einer kollaborativen und branchenübergreifenden Umgebung voranzutreiben. Die OAI wurde von Unternehmen wie Google, IBM, Microsoft, SmartBear Software und weiteren Technologieunternehmen unterstützt.

In der Folge hat die Swagger-Spezifikation unter der Leitung der OpenAPI-Initiative eine Weiterentwicklung erfahren den neuen Namen OpenAPI erhalten. Dies trug dazu bei, die gemeinschaftliche Natur des Projekts widerzuspiegeln. Die Veröffentlichung der ersten Version der OpenAPI-Spezifikation (OpenAPI 2.0) fand im September 2016 statt und basierte auf der damaligen Swagger 2.0-Spezifikation.

Seitdem hat es sich als Standard für die Beschreibung von RESTful-APIs etabliert und ist durch kontinuierliche Weiterentwicklung und Zusammenarbeit in der Industrie gewachsen. Die neueren Versionen brachten eine Reihe von Verbesserungen und neue Funktionen im Vergleich zu OpenAPI 2.0. Darunter eine bessere Unterstützung für JSON-Schema, verbesserte Modularität und erweiterte Möglichkeiten zur Beschreibung von API-Endpunkten sowie Datenmodellen.

Wie funktioniert OpenAPI?

Grundlagen

OpenAPI definiert eine standardisierte, sprachagnostische Schnittstelle, um RESTful-APIs auf eine maschinenlesbare Weise zu beschreiben. Diese Beschreibung enthält Informationen über die verfügbaren Endpunkte, die unterstützten Operationen (wie GET, POST, PUT, DELETE) (Siehe auch CRUD), die möglichen Rückgabewerte und viele weitere Details. Es verwendet das YAML- oder JSON-Format, um diese Beschreibungen auf leicht verständliche und bearbeitbare Weise zu präsentieren.

Vorteile

Standardisierung:

Es bietet eine einheitliche und standardisierte Methode zur Beschreibung von RESTful-APIs. Dadurch gewährleistet bzw. verbessert man die Interoperabilität zwischen verschiedenen Systemen und Technologien.

Dokumentation:

OpenAPI-Dokumente dienen als lebendige Dokumentation der API, die immer auf dem neuesten Stand ist. Dies erleichtert die Zusammenarbeit zwischen verschiedenen Teams und reduziert die Wahrscheinlichkeit von Fehlern und Inkonsistenzen.

Generierung von Code und Client-Bibliotheken:

Durch die maschinenlesbare Natur der Spezifikation können Entwickler automatisch Code-Stubs, Server-Implementierungen und Client-Bibliotheken in verschiedenen Programmiersprachen generieren.

API-Design und -Validierung:

Es ermöglicht Entwicklern, ihre API-Designs frühzeitig zu validieren und Inkonsistenzen zu identifizieren, bevor sie in die Implementierung einfließen.

Interaktive API-Explorer:

Man kann OpenAPI-Dokumente in interaktive API-Explorer, wie z. B. Swagger UI, importieren, um APIs auf benutzerfreundliche Weise zu erkunden und zu testen.

Ökosystem

Das Ökosystem umfasst zahlreiche Tools und Lösungen, die Entwickler bei der Arbeit mit der Spezifikation unterstützen. Einige der bekanntesten Tools sind:

Swagger:

Swagger ist eine Sammlung von Tools, die Entwicklern helfen, ihre APIs zu entwerfen, zu dokumentieren und zu testen. Dazu gehören unter anderem Swagger Editor, Swagger Codegen und Swagger UI.

ReDoc:

ReDoc ist eine Open-Source-Lösung zur Erstellung von API-Dokumentationen auf Basis von OpenAPI-Dokumenten. Es bietet eine übersichtliche und ansprechende Darstellung der API-Dokumentation, die für Endbenutzer leicht zugänglich ist.

Postman:

Postman ist ein weit verbreitetes API-Entwicklungstool, das die Unterstützung für OpenAPI-Spezifikationen bietet. Es ermöglicht Entwicklern, APIs zu entwerfen, zu testen, zu dokumentieren und zu überwachen, indem sie die OpenAPI-Dokumente importieren und mit den integrierten Tools interagieren.

API-Lebenszyklus

Der Einsatz von OpenAPI erstreckt sich über den gesamten API-Lebenszyklus:

Planung:

Entwickler können OpenAPI verwenden, um das API-Design zu skizzieren und Einigkeit über die Funktionsweise und Struktur der API zu erzielen.

Entwicklung:

Mit automatisch generierten Code-Stubs und Client-Bibliotheken auf Basis der Spezifikation können Entwickler schnell und effizient an der Implementierung arbeiten.

Testen:

Es ermöglicht das einfache Erstellen von Testfällen und das automatisierte Testen von APIs auf Kompatibilität und Konformität mit der Spezifikation.

Dokumentation:

Die lebendige Dokumentation auf Grundlage von OpenAPI-Dokumenten stellt sicher, dass API-Benutzer immer auf dem neuesten Stand der API-Funktionalität sind.

Deployment:

Man kann OpenAPI-Dokumente für die automatische Bereitstellung und Konfiguration von APIs auf verschiedenen Plattformen und Umgebungen verwenden.

Überwachung und Wartung:

Damit generierte Tests und Überwachungstools kann man die API-Performance überwachen und Wartungsmaßnahmen effizient durchgeführen.

Alternative API-Spezifikationen

Daneben gibt es noch andere API-Spezifikationen wie RAML (RESTful API Modeling Language) und API Blueprint. Alle drei Spezifikationen haben ähnliche Zielsetzungen, unterscheiden sich jedoch in Syntax, Tool-Unterstützung und Popularität. OpenAPI ist derzeit die am weitesten verbreitete Spezifikation und eine Vielzahl von Organisationen sowie Entwickler bevorzugen es.

Fazit:

OpenAPI ist eine leistungsstarke und flexible Spezifikation, die Entwicklern hilft, RESTful-APIs zu entwerfen, zu erstellen und zu dokumentieren. Es bietet eine standardisierte, sprachunabhängige Schnittstelle und unterstützt den gesamten API-Lebenszyklus von der Planung bis zur Überwachung. Mit einem reichhaltigen Ökosystem an Tools und Lösungen hat es seine Stellung als führende API-Spezifikation im heutigen schnelllebigen Technologieumfeld gefestigt.

Der Beitrag OpenAPI – Die Brücke für nahtlose Kommunikation und effiziente Integration von Web-Services erschien zuerst auf CEOsBay.

Es handelt sich dabei also nicht um den fast gleichnamigen fiktiven Supercomputer HAL 9000. Den man aus dem Science-Fiction-Roman „2001: Odyssee im Weltraum“ von Arthur C. Clarke oder dem gleichnamigen Film von Stanley Kubrick aus dem Jahr 1968 kennt ;).

Es steht für „Hypertext Application Language“ und basiert auf dem HATEOAS (Hypermedia as the Engine of Application State)-Konzept. Das Ziel von HAL ist es, eine einheitliche Methode zum Beschreiben von APIs bereitzustellen. Gleichzeitig soll sie die Interoperabilität zwischen verschiedenen Systemen und Plattformen verbessern.

Im Wesentlichen besteht ein HAL-Dokument aus zwei Teilen: Ressourcen und Links. Eine Ressource ist eine Datenstruktur, die Informationen über eine bestimmte Entität enthält. Links sind Beziehungen zwischen Ressourcen, die es einem Client ermöglichen, auf eine andere Ressource zuzugreifen. Ein Link enthält normalerweise einen URI (Uniform Resource Identifier). Dieser hat eine eindeutige Adresse für eine Ressource, die sie bereitstellt und einen Relationstyp. Dieser beschreibt, welche Beziehung die verknüpfte Ressource zur aktuellen Ressource hat.

Ein typisches HAL-Dokument ist ein simples JSON [RFC7159] und kann folgendermaßen aussehen:

{
  "_links": {
    "self": { "href": "/api/book/123" },
    "author": { "href": "/api/author/456" }
  },
  "title": "2001: Odyssee im Weltraum",
  "authorName": "Arthur C. Clarke",
  "publishedDate": "1968"
}

In diesem Beispiel enthält das HAL-Dokument eine Ressource, die Informationen über ein Buch enthält, sowie Links zu anderen Ressourcen. Beispielsweise dem Autor des Buches. Der Link mit dem Relationstyp „self“ gibt an, dass der Link auf die aktuelle Ressource verweist. Während der Link mit dem Relationstyp „author“ angibt, dass der Link auf den Autor des Buches verweist.

Ein wichtiger Aspekt des HAL-Formats ist, dass es HATEOAS unterstützt. Dies bedeutet, dass alle Ressourcen in einer API durch Links miteinander verbunden sind. Dadurch kann ein Client einer API eine Ressource abrufen und im Anschluss die verfügbaren Links verwenden, um weitere Aktionen auszuführen. Beispielsweise das Abrufen von verwandten Ressourcen oder das Ausführen von Aktionen auf einer Ressource. Dadurch kann man die Flexibilität und Erweiterbarkeit einer API verbessern. Weil man eben neue Ressourcen und Aktionen hinzufügen kann, ohne dass Änderungen am Client-Code erforderlich sind.

Fazit

Insgesamt ist der HAL-Standard eine nützliche Methode zur Beschreibung von APIs. Es gewährleistet eine gute Interoperabilität zwischen verschiedenen Systemen, steigert die Flexibilität und Erweiterbarkeit einer API.

Der Beitrag HAL-Standard – Effiziente Hypermedia-APIs für nahtlose Web-Service-Interaktionen und erweiterbare Systeme erschien zuerst auf CEOsBay.