OpenAPI und RAML – ein Vergleich

APIs sind das digitale Verbindungsstück unserer modernen IT-Systeme und erfordern eine korrekte Dokumentation. Große Unternehmen haben oft Probleme mit der Erstellung und Verwaltung ihrer APIs. Aufgrund fehlender Dokumentation erscheinen Design-Fehler zu spät, um sie noch zu moderaten Kosten zu beheben.

Eine vollständige und durchgängige Dokumentation ist daher entscheidend für die Wartung von APIs, besonders um mit allen Beteiligten ein gemeinsames Verständnis für aktuelle und zukünftige Funktionen festzulegen. Die Dokumentation bestehender APIs sollte möglichst einfach sein und Nutzdatenfragmente und Beispiele mit einschließen. Besonders im Hinblick auf agile Projekte und API-first-Ansätze, die ständigen Änderungen unterliegen, sollte die API diese selbst vorzugsweise automatisch übernehmen. Um diese Herausforderungen zu meistern, stellen wir einen Vergleich der aktuellen Spezifikationen zur Modellierung von RESTful APIs an.

Bei näherer Betrachtung der auf dem Markt verfügbaren Spezifikationen nach Funktionalität, Marktanteil, Integration und Zusammenspiel mit bestehenden Tools sowie der Community blieben nur zwei Spezifikationen übrig, die wir im Folgenden detailliert betrachten.

Praktische Erfahrung

Angesichts der Nutzungsbreite beider Spezifikationen haben wir sowohl in OpenAPI als auch in RAML eine Schnittstelle dokumentiert, um praktische Erfahrung zu sammeln. Dazu haben wir die jeweiligen Entwicklungstools verwendet – OpenAPI bringt die Web-Anwendung swagger-ui mit, während RAML primär mit der API-Workbench, einer IDE, die als Plug-in im Atom Editor ausgeführt wird, erstellt und bearbeitet werden kann. Beide Tools prüfen den menschenlesbaren YAML-Code sofort und zeigen Syntax-Fehler an. Uns hat die API-Workbench von RAML besser gefallen als swagger-ui, obwohl sich die Nutzung beider Anwendungen nur sehr gering unterscheidet.

Die Elemente und Dokumentenstruktur beider Tools sind ebenfalls fast vollkommen gleich. Dennoch bevorzugen wir RAML, da durch einige zusätzliche Elemente eine genauere Modellierung möglich ist. Schließlich haben wir versucht, bestehende XML-Schemadateien unserer Muster-API in unsere Dokumentation zu integrieren. In RAML war das eine Sache von Sekunden, während es in OpenAPI nicht möglich war. Die Modellierung unserer Request-Payload war in OpenAPI nur als JSON-Schema möglich. Das Konvertieren bestehender XSDs in JSON-Schema ist aufwendig, nicht eindeutig und erfordert damit manuelle Nacharbeitung, sodass dieser Anwendungsfall mit OpenAPI nicht gut umgesetzt werden kann. Darüber hinaus wurde das Einbinden von Inhalten aus weiteren Dateien auch nicht so einfach unterstützt, wie in RAML. RAML ermöglicht die Integration beliebiger Dateiinhalte (z.B. Code-Fragmente) in die Dokumentation. OpenAPI unterstützt dagegen nur Verweise auf Kindelemente in externen JSON- oder YAML-Dateien.

Nachdem wir unsere Erfahrungen mit unseren eigenen Anwendungsfällen gemacht haben, haben wir unsere Erkenntnisse zusammengefasst und die Vor- und Nachteile beider Ansätze dokumentiert.

Zusammenfassung

OpenAPI und RAML haben sehr viele Gemeinsamkeiten. Projekte, die mit ausgefallenen Programmiersprachen arbeiten und auch weniger verbreitete Tools integrieren möchten, werden OpenAPI aufgrund der deutlich größeren Auswahl an Code-Generatoren und weiteren Tools im Ökosystem den Vorzug geben. Wenn diese Auswahl nicht entscheidend ist, da die Umsetzung hauptsächlich in Standard-Sprachen wie JAVA erfolgt, ist RAML eine gleichwertige Option. In unserem Demo-Anwendungsfall haben wir uns insbesondere aufgrund der Unterstützung von Code-Wiederverwendung und der Integration bestehender Code-Fragmente für RAML entschieden. Wir mussten bestehende Schnittstellen mit XSD-Payload dokumentieren, die bei Verwendung des OpenAPI JSON-Schema einen zusätzlichen Aufwand verursacht hätten. Sowohl OpenAPI als auch RAML sind weit verbreitet und finden große Unterstützung durch Marktführer, deshalb kann man bei keiner der beiden Möglichkeiten zur API-Dokumentation etwas falsch machen.

Jetzt lesen

Blog - Technologie & Innovation

GraphQL: Eine Alternative zu RESTful-Services

Jetzt lesen

Weitere News

WIR SIND FÜR SIE DA!

Mit Q_PERIOR steht Ihnen ein starker Partner zur Seite.
Wir freuen uns auf Ihre Herausforderung!

18. Mai 2018|