API Definition für leistungsfähige Web-APIs
Wer sich mit der Planung, dem Design und der Entwicklung von API-Schnittstellen befasst, wird sich früher oder später mit der API-Definition und einer der hierfür populären Beschreibungssprachen auseinandersetzen müssen.
Eine gute API zeichnet sich vor allem durch positive Qualitätsmerkmale aus. Hierzu gehören in erster Linie klare Konsistenz, die möglichst einfache Benutzbarkeit und eine geeignete Abstraktion.
Die Bedeutung einer hilfreichen Dokumentation sollte von Anfang an sichergestellt sein und darf niemals unterschätzt werden. Sobald die API auch anderen Entwicklern zur Verfügung gestellt werden soll, muss zwingend eine möglichst ausführliche und umfangreiche API-Definition und Beschreibung dokumentiert werden.
Eine leistungsfähige Web-API ist nur dann erfolgreich, wenn seine Struktur gut dargestellt wird. Technische Angaben wie angebotene Endpunkte, verwendete HTTP-Methoden und Parameter und wie Requests auszusehen haben, sind dabei essentiell. All diese Angaben sorgen zum einen für eine gute Anwendbarkeit und unterstützen bei entsprechender Formulierung auch die automatische Codegenerierung.
Mit welcher Beschreibungssprache eine API-Definition erstellt wird, bleibt dabei dem Entwickler überlassen. Wir beleuchten hier die gängigsten Sprachen wie Open API, Swagger und RAML.
Open-API
Unter der Federführung der Linux-Fundation wurde 2015 eine spezielle Arbeitsgruppe mit der Bezeichnung „Open-API Initiative“ gegründet. Parallel dazu wurde auch Swagger von SmartBear - dem Toolhersteller der bekannten und geschätzten SoapUI - übernommen.
Beide Schritte führten unter dem Aspekt, weiterhin auch herstellerneutral bleiben zu können, zu der Umbenennung von Swagger zur Open-API Specification (OAS).
Inzwischen gehören 26 Mitglieder wie Adobe, SAP, PayPal, eBay, Google, MuleSoft und auch Microsoft dazu. Die konsequente Weiterentwicklung findet auf GitHub statt und eröffnet damit jedem Interessierten die Mitarbeit am Projekt durch Issues oder Pull-Requests.
Mitte 2017 wurde dann die Version 3.0 von Open-API verabschiedet und veröffentlicht. Gegenüber der Vorversion 2.0 konnte besonders auf der obersten Ebene der Hosts und der Sicherheit ein klarer strukturierter Aufbau erreicht werden. Ein weiterer großer Fortschritt wurde bei der Unterstützung des JSON-Schema erzielt. Basierend auf den Formaten JSON oder YAML 1.2 können unterschiedlichste Sprachen wie Java, JScript, .Net, Ruby, Scala oder auch Gitlab angewendet werden.
Auch in Open-API existieren die Ausgangspunkte Contract-/API-First oder alternativ der Programmcode über Code-First. Eine genaue Beschreibung zu Open-API finden Sie in unserem Praxisartikel Open API Spezifikation.
Swagger
Das Swagger API-Projekt wurde im Jahr 2011 von Tony Tam ins Leben gerufen. In der inzwischen hoch vernetzten Geschäftswelt ist es immer wichtiger verteilte Anwendungen mit zentralen Servern über API-Schnittstellen kommunizieren zu lassen.
Lange Zeit wurden APIs vorzugsweise mit der WSDL (Web-Service Description Language) beschrieben. Der wohl größte Nachteil ist die technische Umsetzung von REST-Schnittstellen.
Einer der größten Vorteile von Swagger hingegen ist jedoch das sprachenneutrale und maschinenlesbare Format, welches in der Regel mit JSON oder YAML definiert wird. Zusätzlich bietet es einen leistungsfähigen Erweiterungsmechanismus.
Swagger verfügt zudem noch über die IDL (Interface Definition Language) für eine vereinfachte Programmierung von RESTful-Schnittstellen. Darüber hinaus unterstützt Swagger sowohl die Code-First- wie auch die Contract-/API-First- Entwicklung.
Mit verschiedenen Tools wie die Kernbibliothek (swagger-core), die Visualisierungsoberfläche (swagger-UI), einen leistungsstarken Editor (swagger-Editor) und den Codegenerator (swagger-Codegen) können sehr komfortabel auch leistungsfähige Schnittstellen entwickelt und getestet werden.
Im Rahmen der Beschreibung kann auf Swagger-Tooling zurückgegriffen werden. Hier kann auf dem Quellcode basierend automatisiert eine vollständige Dokumentation erzeugt werden. Eine wesentlich detailliertere Darstellung zu Swagger finden Sie in unserem Artikel Swagger.
RAML
Was mit Swagger als Quasi-Standard für REST-basierte Anwendungen begonnen hat, wurde mit der Open-API Spezifikation klarer strukturiert und erheblich erweitert.
Für die Beschreibung einer REST-API jedoch existiert einerseits kein Standard, auf der anderen Seite wurden SOAP-basierte Web Services bislang immer durch WSDL-Dokumente beschrieben.
Mit RAML (RESTful API Modeling Language) ist nun ein weiteres wichtiges Werkzeug für das API First Development verfügbar. Dabei ist die Anforderung für eine einheitliche Beschreibung von REST-API’s nicht wirklich neu.
Eine API-Definition hält sich in der Regel immer an folgende auszugsweise Inhalte wie Entry-Point’s, Ressourcenpfade, GET-/PUT-Methoden mit Parametern, Geschäftsobjekten, Typen und Fehlercodes.
Die Entwickler von Mulesoft fassten die Notwendigkeit und Vorteile der API-Definition in der modernen Beschreibungssprache RAML zusammen. Dabei profitieren sie im hohen Maße von vielen Vorgängern wie WADL und Swagger.
Eine API-Beschreibung erfolgt dabei im Dateiformat YAML. Damit ist es durch seine vereinfachte Notierung zum einen sehr gut lesbar, auf der anderen Seite sind auch komplexe Hierarchien sehr gut darstellbar. Eine begleitende Dokumentation kann auch über mehrere Kapitel angegeben werden. Für einzelne Methoden können Query-Parameter definiert und als sogenannte „Traits“ auch in anderen Methoden eingesetzt werden. Details und Anwendungsmöglichkeiten zu RAML finden Sie in unseren TECH-Artikel RAML.
Fazit
Die hier aufgeführten Beschreibungssprachen haben eine grundsolide Basis und viele Anhänger. Swagger ist aufgrund der hohen Verbreitung und Toolunterstützung der Quasi-Standard für REST-basierte API-Definitionen. Mit RAML steht eine technisch moderne und leichtgewichtige Beschreibungssprache bereit, die verschiedene Werkzeuge zur API-Modellierung bereitstellt. Die Open API Specification basiert auf Swagger und führt klarere Strukturen und sinnvolle Erweiterungen ein und wird sich langfristig wohl als neuer Standard etablieren.