OpenAPI
Begriffsklärung
Mit OpenAPI (zusammen geschrieben) ist hier ein Standard zu Beschreibung von APIs gemeint. Open API kann aber natürlich auch offene API heißen, was bedeutet, dass sowahl die API selbst im Internet, als auch ihre Beschreibung öffentlich für jedermann verfügbar ist.
| Open API |
Closed API |
|
|---|---|---|
| Zugang |
für Geschäftspartner, Kunden oder jedermann öffentlich. |
nur für interne IT (Intranet, Authentifizierung) |
| Sicherheitsrisiko |
hoch, da schlecht gesicherte APIs einen Angriffspunkt darstellen oder auch durch DoS-Attacken überlastet und damit lahmgelegt werden können. Ein Vorfall kann sich auf das gesamte Unternehmen negativ auswirken. |
geringer, aber ein Mindestschutz vor Missbrauch durch z.B. böswillige Mitarbeiter sollte durch eine Authentifizierung/Autorisierung und regelmäßige Sicherheitsüberprüfung gewährleistet werden |
| Einsatz | keine geschäftskritischen Daten bereitstellen |
Integration von geschäftlichen Anwendungen mit ihren sensiblen, internen Daten oder Back-End-Systemen (Microservices) |
| Benutzerfreundlichkeit | hat hohe Priorität, wenn ein Ökosystem von Drittentwicklern kultiviert werden soll. Eine schlechte Usibility kann dagegen das Gegenteil bewirken bzw. sogar den Ruf des Unternehmens schädigen auch wenn das in der Regel zunächst hingenommen wird. Benutzerfreundlichkeit darf auf jeden Fall nicht auf Kosten der Sicherheit gehen. |
Auch den internen Nutzern sollte ein Mindestmaß an Usibility zur Verfügung stehen. Dazu gehört natürlich eine entsprechende Dokumentation. |
| Versionierung | ist aufwändiger, weil Änderungen nicht dazu führen dürfen, dass bestehende Funktionen für große Gruppen von Nutzern nicht mehr funktionieren. Aktualisierungen müssen auf jedenfalls rechtzeitig mehrfach angekündigt werden, über einen gewissen Zeitraum müssen alte und neue Version laufen und sehr gut dokumentiert sein. |
oft einfacher, Aktualisierungen anzukündigen und vorzunehmen, weil weniger Entwickler involviert sind. Auch sollte sich verwertbares Feedback leichter einholen lassen. |
| Fehler | Fehler, wie z.B. Leistunseinbußen bleiben nicht unbemerkt und müssen daher mit hoher Priorität beseitigt werden. Nötige funktionale Änderungen müssen außerdem der Öffentlichkeit kommuniziert werden. Besonders schwerwiegende Folgen hat das, wenn eine offene API wegen sicherheitsrelevanter Fehler geschlossen werden muss. |
Fehler führen hier oft zum Ausfall oder mindestens Teilausfall von Anwendungen. Das bleibt aber wenigstens häufig von der Öffentlichkeit unbemerkt und Änderungen müssen nur intern kommuniziert werden. |
OpenAPI und Swagger
Es ist in der obigen Gegenüberstellung klar geworden, wie wichtig bei jeder API (auch die geschlossenen) eine verständliche Dokumentation ist. Hierzu dient seit etwa 2015 OpenAPI.
OpenAPI ist eine standardisierte Spezifikation zur offenen und herstellerneutralen Beschreibung von Programmierschnittstellen. Insbesondere lassen sich mit Hilfe von OpenAPI REST-APIs dokumentieren, entwickeln und testen.
Die heutige OpenAPI-Spezifikation Version 3.x ging aus dem Projekt Swagger der Firma SmartBear hervor. Die Spezifikation wurde von SmartBear unter eine offene Lizenz gestellt und zur Pflege und Weiterentwicklung an die OpenAPI-Initiative übergeben. Mitglieder der OpenAPI-Initiative sind neben SmartBear Branchengrößen wie Google, IBM und Microsoft; gefördert wird das Projekt auch von der Linux Foundation.
In einem Vortrag im Rahmen der API Conference stellte Daniel Kieselhorst 2018 Swagger am Beispiel von u. A. Spring Boot vorgestellt und erklärt seine Alltagsintegrierung.
Mit dem Swagger Editor wird eine JSON- oder eine YAML-Datei editiert. Die Benutzeroberfläche Swagger UI der automatisch generierten Dokumentation basiert auf HTML und JavaScript. Damit lässt sich nicht nur die Dokumentation verwalten, sondern es lassen sich z.B. auch Ad-hoc-Tests durchführen.
Mit dem Codegenerator Swagger Codegen, lässt sich für viele Programmiersprachen Code automatisch generieren.
Die
Dokumentationsdatei beginnt mit der Angabe der verwendeten
Spezifikationsversion, dann folgen die generellen Informationen zur API,
sortiert unter der Kategorie info. Swagger trennt auch Host, Pfad
und URL-Schema und gibt sie einzeln an.
Beim Code First-Ansatz lässt sich mit Annotationen im Code eine Schnittstellenbeschreibung generieren. Beim API First-Ansatz liefert Swagger automatisch konsistenten API-Code.