© Excellent backgrounds/Shutterstock.com
Java Magazin
Entwicklung und Dokumentation von REST-APIs

API First mit RAML

Für die Beschreibung von REST-APIs gibt es (glücklicherweise) keinen Standard, der Innovationen bremst, sondern unterschiedliche Formate und Best Practices, die im Laufe der Zeit entstanden und von den Erfahrungen ihrer jeweiligen Vorgänger profitierten. Der jüngste Spross in dieser Reihe ist RAML [1], eine „RESTful API Modeling Language“, die in diesem Artikel als wichtiges Werkzeug für API First Development vorgestellt wird.

Kai Spichale


Gute APIs zeichnen sich durch unterschiedliche Qualitätsmerkmale aus. Hierzu gehören Konsistenz, einfache Benutzbarkeit und geeignete Abstraktionen. Auch die Bedeutung einer hilfreichen Dokumentation darf für ein API nicht unterschätzt bzw. vernachlässigt werden, soll es doch möglichst einfach und von möglichst vielen anderen Entwicklern verstanden und benutzt werden können. SOAP-basierte Web Services werden seit jeher einheitlich durch WSDL-Dokumente in einer für Menschen und Maschinen lesbaren Form beschrieben. Das WSDL-Dokument entspricht einem Vertrag, der zwischen API-Anbieter und API-Nutzer geschlossen wird. Ein modernes WSDL-Pendant speziell für REST-APIs ist RAML. Obwohl diese Open-Source-Beschreibungssprache ursprünglich für REST-APIs entworfen wurde, eignet sie sich ebenfalls für APIs, die nicht alle REST-Anforderungen erfüllen. Auf diese Weise kommt sie für viele Web-APIs, die auf Ressourcen, Methoden und HTTP aufbauen, in Betracht.

Alternative Formate für REST-Metadaten

Die Notwendigkeit, auch REST-APIs einheitlich zu beschreiben und zu dokumentieren, ist nicht neu. API-Designer können heute zwischen unterschiedlichen Formaten für REST-Metadaten wählen. Eine solche Dokumentation hat in der Regel folgende Inhalte: Entry Points, Ressourcenpfade, eine Beschreibung der Methoden zum Zugriff auf die Ressourcen (GET, PUT etc.) samt Methodenparameter. Zur Dokumentation gehören auch die unterstützten Formate (JSON Schema, XML Schema) und die Status- und Fehlercodes. Bevor wir uns RAML im Detail ansehen, folgt in diesem Abschnitt ein Überblick über die wichtigsten Alternativen:

Swagger [2] ist ein Format zur Beschreibung von REST-APIs, das von Reverb entwickelt wird. Es gehört neben WADL laut Google Trends zu den populärsten Technologien in dieser Liste. Zu Swagger gehört Swagger UI, eine Benutzeroberfläche auf Basis von HTML/JavaScript. Swagger UI ist Open Source und dient sowohl zur Dokumentation als auch zur Ausführung von Ad-hoc-Tests. Die eigentliche Stärke von Swagger ist sein umfassendes Ökosystem auf GitHub [3]. Hierzu zählen Codegeneratoren für unterschiedliche Sprachen. Speziell für Java gibt es Annotationen. Ein gutes Beispiel ist der Swagger Petstore [4].

WADL [5] wurde bereits 2009 von Sun Microsystems dem W3C vorgeschlagen, aber nie als Standard verabschiedet. Zur Codegenerierung, Testausführung und Dokumentation existieren Werkzeuge wie beispielsweise Jersey und Apache CXF. Ein anschauliches Beispiel bietet die Jersey-Dokumentation [6].

I/O ...

Java Magazin
Entwicklung und Dokumentation von REST-APIs

API First mit RAML

Für die Beschreibung von REST-APIs gibt es (glücklicherweise) keinen Standard, der Innovationen bremst, sondern unterschiedliche Formate und Best Practices, die im Laufe der Zeit entstanden und von den Erfahrungen ihrer jeweiligen Vorgänger profitierten. Der jüngste Spross in dieser Reihe ist RAML [1], eine „RESTful API Modeling Language“, die in diesem Artikel als wichtiges Werkzeug für API First Development vorgestellt wird.

Kai Spichale


Gute APIs zeichnen sich durch unterschiedliche Qualitätsmerkmale aus. Hierzu gehören Konsistenz, einfache Benutzbarkeit und geeignete Abstraktionen. Auch die Bedeutung einer hilfreichen Dokumentation darf für ein API nicht unterschätzt bzw. vernachlässigt werden, soll es doch möglichst einfach und von möglichst vielen anderen Entwicklern verstanden und benutzt werden können. SOAP-basierte Web Services werden seit jeher einheitlich durch WSDL-Dokumente in einer für Menschen und Maschinen lesbaren Form beschrieben. Das WSDL-Dokument entspricht einem Vertrag, der zwischen API-Anbieter und API-Nutzer geschlossen wird. Ein modernes WSDL-Pendant speziell für REST-APIs ist RAML. Obwohl diese Open-Source-Beschreibungssprache ursprünglich für REST-APIs entworfen wurde, eignet sie sich ebenfalls für APIs, die nicht alle REST-Anforderungen erfüllen. Auf diese Weise kommt sie für viele Web-APIs, die auf Ressourcen, Methoden und HTTP aufbauen, in Betracht.

Alternative Formate für REST-Metadaten

Die Notwendigkeit, auch REST-APIs einheitlich zu beschreiben und zu dokumentieren, ist nicht neu. API-Designer können heute zwischen unterschiedlichen Formaten für REST-Metadaten wählen. Eine solche Dokumentation hat in der Regel folgende Inhalte: Entry Points, Ressourcenpfade, eine Beschreibung der Methoden zum Zugriff auf die Ressourcen (GET, PUT etc.) samt Methodenparameter. Zur Dokumentation gehören auch die unterstützten Formate (JSON Schema, XML Schema) und die Status- und Fehlercodes. Bevor wir uns RAML im Detail ansehen, folgt in diesem Abschnitt ein Überblick über die wichtigsten Alternativen:

Swagger [2] ist ein Format zur Beschreibung von REST-APIs, das von Reverb entwickelt wird. Es gehört neben WADL laut Google Trends zu den populärsten Technologien in dieser Liste. Zu Swagger gehört Swagger UI, eine Benutzeroberfläche auf Basis von HTML/JavaScript. Swagger UI ist Open Source und dient sowohl zur Dokumentation als auch zur Ausführung von Ad-hoc-Tests. Die eigentliche Stärke von Swagger ist sein umfassendes Ökosystem auf GitHub [3]. Hierzu zählen Codegeneratoren für unterschiedliche Sprachen. Speziell für Java gibt es Annotationen. Ein gutes Beispiel ist der Swagger Petstore [4].

WADL [5] wurde bereits 2009 von Sun Microsystems dem W3C vorgeschlagen, aber nie als Standard verabschiedet. Zur Codegenerierung, Testausführung und Dokumentation existieren Werkzeuge wie beispielsweise Jersey und Apache CXF. Ein anschauliches Beispiel bietet die Jersey-Dokumentation [6].

I/O ...

Neugierig geworden?


    
Loading...

Angebote für Teams

Für Firmen haben wir individuelle Teamlizenzen. Wir erstellen Ihnen gerne ein passendes Angebot.

Das Library-Modell:
IP-Zugang

Das Company-Modell:
Domain-Zugang