So geht REST – W-JAX 2015

In der ersten Novemberwoche fand in München die W-JAX statt und die Saxonia Systems AG (seit 03/2020 ZEISS Digital Innovation) war als Gold Partner mit einem Stand und drei Speakern dabei. Die Themen reichten in diesem Jahr vom klassischen Java Enterprise über Microservice Architekturen, REST, Reactive Programming, DevOps und Continuous Delivery zu Testing und Security.

Für die Saxonia Systems AG sprachen Alexander Casall, Manuel Mauky und Kay Grebenstein zu verschiedenen Themen rund um JavaFX. Schade war, dass der Vortrag von Alexander und Manuel am Mittwoch parallel zum Vortrag von Kay angesetzt war, so teilte sich die JavaFX interessierte Zuhörerschaft auf beide Vorträge auf.

Ein Thema, welches in diversen Vorträgen im Vordergrund stand, waren RESTful Webservices. Da ich in den letzten Jahren in Projekten immer öfter auf diese Thematik gestoßen bin, habe ich ein paar dieser Vorträge besucht, um Wissen zu erweitern, zu vertiefen oder auch einfach nur abzugleichen, wie gut oder schlecht man vielleicht selbst in der Vergangenheit an dieses Thema gegangen ist.

REST – ein Überblick

Einen Überblick über das Thema lieferte Silvia Schreier (innoQ) mit ihrem Vortrag „REST 2015“. REST – der REpresentational State Transfer – ist prinzipiell nichts Neues, wurden die Grundlagen dafür schon Mitte der 90er Jahre von Roy Fielding definiert. Doch erst in den letzten Jahren sind RESTful Webservices verstärkt im Kommen. Hierbei werden die Ressourcen des Dienstes – beispielsweise Bücher und Autoren bei einem Bücherservice – per eindeutiger URI zugreifbar gemacht. Zum Beispiel würde GET /books/123 eine Repräsentation eines speziellen Buches liefern, GET /books eine Liste aller Bücher.

Operationen auf diesen Ressourcen werden mit HTTP Verben abgebildet. Anstelle einer speziellen URI zum Ändern eines Datensatzes wie /authors/456/update, wird die Ressource verändert, indem beispielsweise ein PUT oder PATCH Request auf sie ausgeführt wird. Ebenso dient DELETE zum Löschen und POST zum Erzeugen neuer Ressourcen. Für die Antwort bietet HTTP dem REST Service eine einfache Möglichkeit, den Aufrufer über den Status der Anfrage zu informieren. Die 200er Status Codes bedeuten eine erfolgreiche Anfrage, 300er Weiterleitungen, 400er Fehler des Clients und 500er Fehler auf Server Seite. Zusätzlich dazu gibt es eine Vielzahl standardisierter Header, welche Client und Server nutzen können und sollten, um beispielsweise den Typ des Inhalts auszuhandeln, Informationen über Autorisierung und Caching anzugeben und vieles mehr.

Ein wesentliches Architekturprinzip für gute RESTful Webservices ist HATEOAS – Hypermedia as the Engine of Application State. Hier erfolgt die Navigation des Clients ausschließlich über URLs, die entweder in den Ressourcen oder den Header-Informationen vom Server bereitgestellt werden. Hierdurch wird eine lose Kopplung erreicht, was es dem Schnittstellenanbieter erleichtert, Änderungen an dieser zu machen.

Neben diesen grundsätzlichen Informationen wurden noch eine Reihe von Best Practices zu weiteren Themen rund um RESTful Webservices gegeben. Beispielsweise lassen sich alle Mechanismen gleichermaßen nutzen, um auch die Dokumentation der eigenen Schnittstelle als spezielle Ressourcen verfügbar zu machen. Der Überblick wurde abgerundet durch das Thema Sicherheit. Hier gibt es viele Möglichkeiten der Authentifizierung und Autorisierung wie Basic Auth, Cookie basierte Mechanismen, OAuth 1 und 2, OpenID Connect und weitere Verfahren. Welches sich in der jeweiligen Anwendung eignet oder genutzt werden sollte, kommt auf den Anwendungsfall und die Art der Clients an.

Spring Data REST

Nach der Theorie stellt sich die Frage, wie sich nun REST-konforme Schnittstellen mit Java entwickeln lassen. Da in meinen bisherigen Projekten immer Implementierungen des JAX-RS Standards zum Einsatz kamen, war es interessant sich den Ansatz von Spring anzuschauen. Den hierzu passenden Vortrag „Spring Data REST – Repositories meet Hypermedia“ gab es von Oliver Gierke (Pivotal Software, Inc.). Out of the Box generiert Spring Data REST HATEOAS-konforme Ressource-Repräsentationen im HAL-Format aus den Domänenobjekten. Das HAL – Hypertext Application Language – Format definiert die Art und Weise wie Hyperlinks in Ressourcen dargestellt werden. Bei einer HAL-konformen Schnittstelle kann der Client allein durch die gegebenen Links und deren Relationen durch die komplette Schnittstelle navigieren. Spring kümmert sich automatisch, um die Übersetzung des Domänenmodells, indem beispielsweise aggregierte Objekte direkt als Sub-Ressourcen, Relationen zwischen Objekten als Links oder IDs als URIs abgebildet werden. Spring Data REST bietet bereits vieles, was – zumindest bis jetzt – bei JAX-RS noch händisch gemacht werden muss. Je nachdem, worauf der Fokus im Projekt gelegt wird, kann sich der Umstieg auf das Spring Ökosystem durchaus lohnen.

Dokumentation von REST Schnittstellen

Ein Thema welches gern mal ignoriert oder zumindest stiefmütterlich behandelt wird, ist die Dokumentation. Doch gerade bei Schnittstellen ist diese oft unverzichtbar für die Anwender der Schnittstelle bzw. die Entwickler, welche diese Schnittstelle nutzen sollen. Welche Möglichkeiten es gibt, sich mit Hilfe von Open Source Werkzeugen Dokumentationen von REST Schnittstellen generieren zu lassen, war Thema in Martin Walters (Deutsche Welle) Vortrag „REST-Architekturen erstellen und dokumentieren“. Hierbei gibt es verschiedene Ansätze, wie apiary.io zum Schreiben von Dokumentationen in einer Wiki-Syntax oder Javadoc basierten Lösungen wie SpringDoclet und apidoc.js, bei denen spezielle Kommentare im Quellcode genutzt werden für die automatische Generierung von Dokumentationen. Das umfangreichste Werkzeug bzw. Sammlung von Werkzeugen bietet Swagger. Dokumentationen können hier mittels Annotationen aus dem Code heraus erzeugt, mit JSON oder YAML geschrieben oder mit Hilfe von Editoren erzeugt werden. Aus der JSON Definition können wiederum Client- und Serverendpunkte in verschiedensten Sprachen generiert werden. Des Weiteren bietet Swagger ein UI zur Darstellung der Schnittstelle mit der Möglichkeit, diese direkt auszutesten.

Fazit

Für mich war es die erste W-JAX Teilnahme und ich wurde nicht enttäuscht. Es gab viele Themen und wirklich gute Vorträge. Neben den bereits im Detail erwähnten Vorträgen rund um REST möchte ich hier auf jeden Fall noch Axel Fontaine (Boxfuse GmbH) mit seinem Vortrag „Immutable Infrastructure auf AWS“ und Steffen Müller (Incloud GmbH) mit „Cross-Plattform-App-Entwicklung“ nennen. Beide Vorträge waren sowohl inhaltlich als auch vom Stil her sehr interessant und erfrischend. Was ich persönlich ein wenig schade fand, war die große Anzahl von jeweils 10 parallelen Vorträgen. So blieb vieles auf der Strecke, da es oft zwei oder drei parallele Themen gab, die ich gern besucht hätte. Trotz allem komme ich gern wieder!

Dieser Beitrag wurde verfasst von: