OAS-Alternativen RAML, API Blueprint & Co. – OpenAPI-Konkurrenz?

OpenAPI ist zwar im Bereich der RESTful-Schnittstellen der größte Player, aber wie sieht es mit alternativen Spezifikationen aus? Können die angestaubten RAML und API Blueprint dem wirklich etwas entgegensetzen?

Erst kürzlich konnten Sie hier lesen, wie eine vorhandene Datenbank um eine Schnittstelle nach OpenAPI-Spezifikation (OAS) erweitert wird und etliche weitere Beiträge drehen sich um die allgegenwärtige Web-API.

OpenAPI in der Praxis (1)

Apps mit API und Dokumentation ausstatten

Doch es gibt einige Alternativen, insbesondere RESTful API Modeling Language (RAML) und API Blueprint. Wobei das mit den „Alternativen“ so eine Sache ist: Beide betonen, komplementär zu OpenAPI zu sein – und überhaupt, beide Projekte haben sich schon vor Jahren der OpenAPI Initiative angeschlossen. Daher stellen sich die Fragen: Sind es also überhaupt Alternativen? Sind sie relevant?

RAML

RAML ist als Projekt von MuleSoft 2013 entstanden, weil man dort mit der Entwicklung von Schnittstellen mittels OAS nicht zufrieden war. Mittlerweile gehört RAML zu Salesforce.

Die Design-Sprache setzt auf YAML-Syntax – heute ein populärer Standard für Konfigurationen vom Netzwerkadapter bis zu Cloud-Instanzen. Bei OAS darf es JSON oder YAML sein. Der Hauptzweck von RAML war von Anfang an das Design von Schnittstellen – wohingegen OAS meist als Werkzeug zum Beschreiben vorhandener APIs begriffen wurde. Nun, letztlich waren die beiden API-Spezifikationen für beide Zwecke nutzbar.

Schaut man sich die Situation heute an, sieht das Ganze etwas anders aus: OAS hat sich massiv weiterentwickelt und die meisten Features, die RAML ursprünglich voraus hatte, mittlerweile ebenfalls zu bieten. Überhaupt wird RAML nicht sonderlich aktiv entwickelt, im offiziellen RAML-Repository auf GitHub gibt es schon seit Jahren keine Aktualisierungen abseits einzelner Tools mehr. Kein Wunder, schließlich hat sich RAML längst der OpenAPI Initiative angeschlossen und den ursprünglich proprietären Code geöffnet.

Für RAML gibt es allerlei Tools, zum Beispiel PHP-Parser, Konverter zum Beispiel nach JSON, den offiziellen Playground für erste Schritte, Plugins für IDEs und so weiter. Mit der großen Menge an OAS-Software kann das Projekt allerdings nicht konkurrieren.

Trotzdem gibt es nach wie vor RAML-Nutzer. Neben der Vorliebe für die Syntax oder einzelner Features, bevorzugen viele Entwickler immer noch RAML für das Modellieren von APIs, gerne auch kollaborativ im Team – weil der Aufbau vielen einfacher erscheint. Und da sich RAML-Projekte nach der Entwicklung einfach nach OAS konvertieren lassen, bietet sich eine komplementäre Nutzung an: RAML für das Design, OAS zum Testen und produktive Systeme.

Für Neueinsteiger stellt sich jedoch die Frage, ob es wirklich hilfreich ist, gleich zwei Systeme zu erlernen – die RAML-Vorteile dürften vor allem für Bestandsnutzer oder sehr große Projekte interessant sein.

API Blueprint

API Blueprint stammt ebenfalls aus dem Jahr 2013, entwickelt von Apiary und später von Oracle akquiriert. Doch schon 2016, ein Jahr nach Gründung der OpenAPI Initiative in der Linux Foundation, hat sich API Blueprint dieser ebenfalls angeschlossen.

Bei API Blueprint stand ursprünglich vor allem die Dokumentation von APIs im Vordergrund, heute wirbt das Projekt speziell mit dem kollaborativen Design von Schnittstellen.

Beim Format setzt das Projekt auf das weniger bekannte MSON, die Markdown Syntax for Object Notation. Und hier dürfte heute für viele der größte Reiz liegen, da die Notation sehr gut lesbar und daher auch gut für Diskussionen und Demonstrationen geeignet ist. Hier mal ein kleines Beispiel von Apiary selbst. Zunächst ein simples Objekt in JSON:

Das gleiche Objekt in MSON:

Die Markdown-Syntax ist extrem simpel, größtenteils intuitiv und nahezu allgegenwärtig. Allerdings: Auch YAML ist mittlerweile im Alltag kaum noch wegzudenken – etwas fehleranfälliger, aber ähnlich gut lesbar. JSON kann bezüglich der Verarbeitung durch weitere Werkzeuge punkten. Ein OAS-Dokument auf YAML-Basis, das letztlich aber als JSON-Dokument verwandt wird, scheint ein guter Kompromiss zu sein.

Schaut man sich das Tooling von API Blueprint an, sieht man zunächst eine wirklich umfangreiche Sammlung mit den üblichen Editoren, Mock-Servern, Konvertern, Parsern etc. – die auf den zweiten Blick allerdings meist kaum noch gepflegt werden, viele der offiziell gelisteten Projekte stehen im Grunde seit den Anfangstagen still.

Der Oracle-Hintergrund könnte auf viele Managements natürlich verlockend wirken, ein Blick auf die angebotenen Pläne dürfte dies jedoch schnell in Zweifel ziehen. Denn die Plänse sind nicht „Free“ sondern „deprecated“ gelistet.

Angenehm ist allerdings die klare Nutzerführung, schließlich ist der Einstieg in die API-Welt nicht wirklich trivial. Und Apiary zeigt den gewünschten Weg klar auf: API in einfacher Sprache verfassen, per Mock-Server demonstrieren und dann per GitHub-Sync weiterentwickeln.

Nach wie vor Teil des Konzepts: die Dokumentation. Diese wird automatisch erstellt, was allerdings kein USP mehr ist, auch in der OAS-Welt lassen sich wunderbare, interaktive Dokumentationen erzeugen, zum Beispiel auch per Redoc, wie unsere kurze OpenAPI-Serie ebenfalls zeigt.

OpenAPI in der Praxis (2)

Datenbank um API und Dokumentation erweitern

OpenAPI vs. World

Warum sich OpenAPI durchgesetzt und RAML wie API Blueprint auf die Plätze verwiesen hat, scheint relativ klar: OAS/Swagger war von vornherein Tool-agnostisch. Hinter API Blueprint und RAML standen API-Tool-Anbieter – was für Anwender ein mögliches (späteres) Vendor-Lock-in hätte bedeuten können.

Swagger hat es geschafft, dass sich um OAS eine große, dynamische Open-Source-Community bildete und natürlich sollte man nicht vergessen, dass OAS zuerst da waren – und dass First-to-Market-Produkte gute Chancen auf die Marktführerschaft haben – ganz abseits von der Frage, welches Produkt qualitativ wirklich besser ist, demonstriert Windows bis heute äußerst erfolgreich.

Aber ist denn nun OAS wirklich besser als RAML und API Blueprint? Auf der reinen Spezifikationsseite gibt es nach wie vor Diskussionen. Auch wenn sich OAS ständig weiterentwickelt, argumentieren einige Nutzer immer wieder vor allem für die einfache API-Blueprint-Syntax und den verständlicheren Aufbau von RAML-Dokumenten.

Auch einzelne Features werden immer wieder hervorgehoben, die für sehr spezifische Aufgaben bei dieser oder jener Variante besser seien. Hier kommt es aber wirklich auf den Einzelfall an, wirklich entscheidende Killer-Features kann wohl keine OAS-Alternative für sich verbuchen.

Tendenziell stellt sich die Frage aber auch nur in Maßen: OAS ist bezüglich der Verbreitung soweit weg von allen anderen Spezifikationen, dass man es getrost als Quasi-Standard sehen darf – und die vermeintliche Konkurrenz allenfalls als Speziallösungen für Spezialfälle oder komplementäre Hilfsmittel.

Eine Frage, die sich eher stellt als OAS oder API Blueprint oder RAML: SmartBear oder Apiary oder Postman oder Apidog oder … Die Auswahl an API-Entwicklungsplattformen ist deutlich größer, die Entscheidung für eine deutlich komplexer und meist werden alle Spezifikationen unterstützt.

Als Tipp für API-Einsteiger: Um OpenAPI kommt man in der Praxis kaum herum, die Notation ist beileibe nicht so viel komplizierter als bei etwa API Blueprint, es gibt das größte Angebot an zugehöriger Software, die meisten Features, die umfangreichste Dokumentation und selbst der praktische Einstieg ist mit etwas Entwicklungserfahrung binnen weniger Tage zu bewerkstelligen – und somit ist OpenAPI auch der beste Einstieg. Andere Spezifikationen für bestimmte Zwecke lassen sich später immer noch, und dann sehr fix erlernen.

Im Dunstkreis der OpenAPI-Spezifikation

OAS-Alternativen – spannende und freie OpenAPI-Tools

(ID:50188552)