documentation:
- title: Home
content: |
Welcome to the airline Fly Away. We are an european low cost airline. You can find the cheapest airline fares within Europe.
- title: Languages
content: |
Please select a language of your choice for our airline API. We offer the following languages: English, German, Spanish, French and Italian. See our library [languages libraries](http://www.google.com).RESTful API Modeling Language (RAML)
Der stetig steigende Anteil an Webanwendungen basiert auf der ebenso zunehmenden Vernetzung zwischen Kunden und Unternehmen. Die Interaktion der Teilnehmer wird dabei über API’s geregelt, welche die Apps und die IT-Infrastruktur digital miteinander verbinden. Aus diesem Grund ist es besonders wichtig, dass eine API für seine Anwender möglichst flexibel und transparent gehalten wird. Auch Designfehler in der Projektierungsphase können mit einer gut strukturierten Dokumentation schnell und sicher aufgefunden und behoben werden. Besonders Projekte mit einem API-First-Ansatz unterliegen oft einem Änderungsprozess, der eine lückenlose Darstellung der Schnittstellen und Parameter unabdingbar macht.
Mit RAML (RESTful API Modeling Language) existiert eine speziell auf das API-First-Prinzip und die Modellierung von RESTful-API’s ausgelegte Beschreibungssprache. Das Ziel ist hier vor allem die lückenlose Bereitstellung aller Informationen für die Beschreibung und Generierung einer API. Von MuleSoft bereits 2013 als Spezifikation definiert, liegt RAML heute in der aktuellen Versionierung 1 mit dem Release-Datum 2017-07-06 vor. Die Notation der API erfolgt dabei im YAML 1.2 Format. Als Sprachunterstützung werden Java, Node.js, Mule, Phyton und IOT angeboten. Die RAML-Spezifikation wird neben dem Gründer MuleSoft auch von beispielsweise Cisco, VMWare, .Net, PayPal, SOA Software, Kin Lane und AngularJS unterstützt.
Die API-Kernelemente in 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.
Docs
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:
Details
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:
title: Airline Fly Away API
version: v1
baseUri: http://api.dataliquid.com/airline/{version}
description: This API allows to interact with our airline Fly Away API.
mediaType: application/jsonDer 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.
Security
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:
securedBy: [oauth_2_0]
securitySchemes:
oauth_2_0:
type: OAuth 2.0
displayName: OAuth 2.0
description: |
This API supports OAuth 2.0. The necessary `ClientId` and `ClientSecret` will be supplied by the _provider_ of the API. `Access-Tokens` will be issued by means of Id and Secret and are subjected to `TimeToLive`, short TTL, that is provided when the token is issued. Expired Tokens are rejected by the API with the HTTP Status `403`.
describedBy:
headers:
Authorization:
type: string
displayName: Authorization
description: |
Used to send a valid OAuth 2 access token. Do not use with the "access_token" query string parameter.
example: Bearer MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3
queryParameters:
access_token:
type: string
displayName: Access Token
description: |
Used to send a valid OAuth 2 access token. Do not use with the "Authorization" header.
example: MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3
responses: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:.
Ressources
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:
/flights:
get:
displayName: Search flights
description: Customer searches for flights by using different filters.
queryParameters:
departure_airport:
type: string
displayName: Departure airport
description: Departure airport according to the IATA airport code. It's a threeletter
code designating many airports around the world.
example: "BER"
required: false
destination_airport:
type: string
displayName: Destination airport
description: Destination airport according to the IATA airport code. It's a
three-letter code designating many airports around the world.
example: "LON"
required: false
flight_type:
type: string
displayName: Flight type
description: Flight is either one way or return.
example: "One way"
required: false
outgoing_flight_date:
type: date-only
displayName: Outgoing flight date
description: The date of the outbound flight.
example: "2018-12-11"
required: false
return_flight_date:
type: date-only
displayName: Return flight date
description: The date of the return flight.
example: "2018-12-18"
required: false
passengers:
type: number
displayName: Passengers
description: Number of flight passengers.
example: 1
required: false
responses:Types
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:
types:
FlightSearchType:
type: object
displayName: Flight search type
description: User searches for flights and receives information about available flights, date and time, flight number.
properties:
departure_airport:
type: string
displayName: Departure airport
description: Departure airport according to the IATA airport code. It's a three-letter code designating many airports around the world.
example: "BER"
destination_airport:
type: string
displayName: Destination airport
description: Destination airport according to the IATA airport code. It's a three-letter code designating many airports around the world.
example: "LON"
price:
type: PriceType
displayName: Price
description: Price of the flight.
example:
price: 79.99
currency: "EUR"Errors
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:
responses:
404:
body:
application/json:
type: ErrorType
example: |
{
"reason": "RESOURCE_NOT_FOUND",
"message": "Resource not found",
"trace_id": "550e8400-e29b-11d4-a716-446655440000"
}Vor- und Nachteile von RAML
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.
Fazit
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.