RESTful API Modeling Language (RAML)

Eine möglichst detaillierte und vollständige Dokumentation zu einer API ist hinsichtlich der Verwendbarkeit und Wartung besonders wichtig. Inhaltlich müssen alle wichtigen Parameter, Geschäftsobjekte, Fehlercodes und Zusatzinformationen genau und idealerweise auch mit kurzen Beispielen beschrieben werden. Die im Folgenden aufgezeigten Kernelemente sollten daher in jeder API-Beschreibung vorhanden sein und möglichst detailliert dargestellt werden. Wir beschreiben die verschiedenen Bereiche mit einem fiktiven Beispiel einer Fluggesellschaft, in der unterschiedliche Aktionen wie Buchungen, Stornos oder Abfragen von Informationen zu leisten sind.

Für eine möglichst detaillierte Beschreibung der API-Bestandteile können in der Sektion docs entsprechende Dokumente benannt werden. Auch eine Benutzeranleitung kann hier in Form von Links und Includes integriert werden. Hierzu stehen die zwei Parameter documentation: und title: zur Verfügung, um einen Referenzlink zu beschreiben. Es ist auch eine Mehrfachnennung von Links und Beschreibungen möglich. Der folgende Quelltextauszug zeigt ein Beispiel:

Grundlegende Informationen zu der vollständigen API werden in der Sektion Details notiert. Hierfür stehen verschiedene Parameter wie auszugsweise info:, title: oder servers: zur Verfügung. Im nachfolgenden Quelltextauszug sehen Sie ein Beispiel zu unserer fiktiven Airline:

Der Parameter title: sollte die grundlegende Funktionalität der API beschreiben. Die Versionsangabe im Parameter version: ist für die Revisionsverwaltung von Interesse. Mit dem Parameter baseUri: wird der Pfad zur API angegeben, der auch eine Ebene der Versionierung beinhalten kann. In description: vergeben Sie weitere Informationen zur API. Unter mediaType: verzeichnen Sie die für die API verwendete Formatsprache.

In dieser Sektion werden alle Angaben bezüglich der Sicherheit notiert. Hier stehen in der Regel die Authentifizierungsmethoden, die in der API angewendet werden. Über verschiedene Angaben werden die Sicherheitsebene und weitere Parameter definiert. Der folgende Quelltextabschnitt beschreibt exemplarisch die Authentifizierungseinstellungen für unser fiktives Unternehmen:

Der erste Parameter securedBy: definiert das anzuwendende Authentifizierungsverfahren, welches als Root über die ganze API gültig ist. Darauf folgen eine oder mehrere Definitionen mit einem Satz an Parametern wie auszugsweise type:, displayName:, describedBy: und queryParameter:. Mit diesen Angaben wird das angewendete Autorisierungsverfahren im Detail beschrieben. Hierauf folgen noch Angaben zum Access-Token access_token: und die möglichen Response-Codes responses:.

Um den Zugriff auf die verschiedenen Ressourcen über die API zu definieren, werden im http-Protokoll unterschiedliche Zugriffsmethoden verwendet. In der Regel kommen hier die vier gängigsten Methodenaufrufe in Frage. Diese signalisieren dem Browser, wie er mit einer Anfrage umzugehen hat und wie die mitgeführten Parameter verwendet werden sollen. In der nachfolgenden Auflistung werden die vier Methodenaufrufe kurz vorgestellt:

GET - Über die GET-Methode kann beispielsweise lesend auf eine Ressource zugegriffen werden, ohne die Bestandsdaten zu verändern. Für unsere fiktive Fluggesellschaft würde dieser Aufruf einer Abfrage über einen bestimmten Flug entsprechen.

POST - Die POST-Methode ist vorgesehen, um eine neue Ressource zu erstellen. Dabei darf die zu generierende Ressource noch nicht im System vorhanden sein. Dieser Methodenaufruf entspricht in unserem Beispiel der Erzeugung einer neuen Kundenbuchung für einen Flug.

PUT - Über diese Methode kann eine Änderung bzw. Ergänzung an eine bereits im System vorhandene Ressource vorgenommen werden. Hier wäre eine Änderung der Flugdaten wie beispielsweise der Abflugzeit in einer bestehenden Buchung ein entsprechendes Beispiel.

DELETE - Wenn eine Ressource im System nicht mehr gebraucht wird, kann mit diesem Methodenaufruf eine Löschung durchgeführt werden. Dies wäre der Fall, wenn ein Kunde einen bereits gespeicherten Buchungssatz wieder entfernen möchte.

In der API werden zu jedem Methodenaufruf die entsprechenden Parameter detailliert aufgeführt. Am Beispiel unserer Fluggesellschaft sucht ein Besucher auf unserer Webseite unter Verwendung der Suchparameter (queryParameters) gezielt nach passenden Flügen. Im folgenden Quelltext finden Sie die exemplarische Definition der GET-Methode auszugsweise wieder:

Ein wesentlicher Bestandteil der API-Definition ist die detaillierte Darstellung der verwendeten Geschäftsobjekte mit allen benötigten Parametern. Hier finden wir dann auch die Objekteigenschaften wie departure_airport:, destination_airport: oder price: Einen dieser Objekttypen für die Flugsuche (FlightSearchType) werden wir im folgenden Quelltextauszug kurz vorstellen:

Ein weiterer wichtiger Abschnitt in der API-Definition sind die Statusmeldungen der Kommunikation. Diese sollten möglichst detailliert aufgeführt werden, um eine mögliche Fehlersuche bzw. Benutzermeldung effektiv durchführen zu können. Die Rückgabe einer Fehlermeldung erfolgt dabei im JSON-Format, wie der folgende Quelltextauszug zeigt:

Gegenüber anderen Auszeichnungssprachen wie Open API bietet RAML eine einfache und komfortable Möglichkeit, wiederkehrenden Quellcode und Schemas einbinden zu können. Zudem existiert eine durchaus aktive Community, die einen hervorragenden Support leistet und Code-Snippets zur Verfügung stellt. Mit professionellen Tools wie die Atom Plugin API Workbench oder das Mule Studio ist eine schnelle und komfortable Projektierung möglich. Nachteilig sind hier die wenigen verfügbaren Tutorials, die einem Neuling den Einstieg erleichtern könnten. Problematisch ist auch die fehlende Abwärtskompatibilität der unterschiedlichen Versionen sowie die relativ geringe Sprachenvielfalt gegenüber andern Beschreibungssprachen.

Wer vom Grundsatz her schnelle und saubere Designs für RESTful-API’s benötigt, ist mit der Beschreibungssprache RAML derzeit klar im Vorteil. Besonders mit Blick auf agile API-First-Projekte sollte die Dokumentation möglichst einfach aber transparent gehalten werden. Aufgrund der flexiblen Wiederverwendbarkeit von Objekten und Codefragmenten kann RAML gegenüber der Konkurrenz deutlich punkten. Die Integration von XML-Schemata ist mit RAML in Sekunden erledigt. Vor allem die Bedienung der API Workbench ist sehr einfach und intuitiv gelöst. Dennoch bleibt anzumerken, dass aufgrund neuerer Entwicklungen und fortschreitender Standards die Auszeichnungssprache Open API deutlich an Zulauf gewinnt und in absehbarer Zeit wohl als neuer Standard definiert wird.