RESTful API Modeling Language (RAML)

Gute API Dokumentationen sind ein maßgeblicher Faktor für die Verbreitung der zugehörigen Schnittstellen. Gut geschrieben und visualisiert erleichtern sie einem Entwickler den Umgang und die Verwendung der API. Die Erstellung hingegen ist oft mühsam und läuft im täglichen Entwickleralltag leider eher unter Fleißarbeit. Hier schafft die RESTful API Modeling Language (RAML) Abhilfe, indem es die Erstellung und Visualisierung solcher Dokumentationen erleichtert.

Was ist RAML?

Die RESTful API Modeling Language (RAML) ist eine auf der Objekt-Serialisierungs-Syntax YAML basierende Spezifikation zum Beschreiben von Schnittstellen und deren Verwendungen. Vor allem zur Dokumentation von RESTful-APIs bietet RAML komfortable Möglichkeiten.

Aufbau der RAML-Datei

Der erste Abschnitt widmet sich den Meta-Informationen, die für die komplette API gültig sind. Dazu gehören unter anderem title, version und baseUri. Die baseUri wird dann beispielsweise für jede Methode der API als Präfix verwendet.

ersion: v1.2
baseUri: http://{env}.example.ch/api
baseUriParameters:
 env:
 description: The environment
mediaType: application/json

Als nächstes geht es darum, die einzelnen Ressourcen zu erstellen, die über die Schnittstelle abgerufen werden können. Über /users/all könnte man sich nun Beispielswiese alle verfügbaren User holen.

/users
   /all:

Zudem gibt es die Möglichkeit den Zugriff auf einen speziellen Vertreter einer Ressource zu definieren. So erhält man zum Beispiel mit der Ressource /users/{id} einen bestimmen User mit der angegebenen ID.

/users: 
  /{id}:

Für die definierten Ressourcen lassen sich dann die verfügbaren Methoden definieren. Für RESTful Services können hier z.B. Aufrufe zu den HTTP-Methoden GET, PUT, POST und DELETE definiert werden, dabei kann jede Medthode nur einmal aufgeführt werden.

   get:
    description: Alle User.
    responses:
   post:
    description: Erstellung eines Users.
    responses:

Abschließend können für die aufgeführten Methoden Responses definiert werden. Diese werden unterschieden nach dem HTTP Status Code zu dem sie ausgeliefert werden. Unter dem Attribut body wird das Rückgabeformat definiert. Für die konkrete Beispielantwort lässt sich sehr einfach auf ein externes JSON-Dokument verweise. Hierzu verwendet man das Schlüsselwort example. Der Verweis auf externe JSON-Dateien hält die eigentliche RAML-Datei kompakt und vereinfacht das gezielte Bearbeiten der JSON-Dateien im laufenden Entwicklungsprozess.

Falls benötigt, können für jede Methode noch Query-Parameter zur Übergabe definiert werden.

/users:
  get:
   description: Liste aller User.
   queryParameters:
       active: false
   responses:
    200:
     body:
      application/json:
       example: !include examples/users-get.json
  post:
   description: Erstellung eines Users.
   responses:
    200:
     body:
      application/json:
       example: !include examples/users-post.json

Visualisierung als HTML-Seite

Im Anschluss an die Definition, können wir aus den entstandenen RAML-Dateien Tool-gestützt eine HTML-Seite generieren. Dazu verwenden wir das Node.js-Modul raml2html (RAML zu HTML Generator). Dieser kann mit Hilfe von npm wie folgt installiert werden:

npm i -g raml2html

Nach der erfolgreichen Installation ist der Generator sehr einfach zu verwenden.

raml2html example.raml > example.html

Auf der genrierten HTML-Seite werden die Informationen der API und deren Methoden übersichtlich dargestellt, sodass dem Entwickler eine einheitliche Dokumentation zur Verfügung steht. Der Generator bietet darüber hinaus noch die Möglichkeit die erstellte Seite mit Hilfe von Themes zu gestalten.

Im Standard-Theme sieht das dann wie folgt aus:

Hier können nun per Klick auf die jeweilige Methode deren Details eingesehen werden.

RAML bietet somit die Möglichkeit aus einfachen YAML-Dateien ansprechende HTML-Seiten zu generieren. Die Entwickler einer API können daher mit wenig schreibaufwand ansprechende API-Dokumentationsseiten erstellen und diese als HTML-Seite zur Verfügung stellen.