Das Richardson Maturity Model (RMM) von Leonard Richardson aus dem Jahr 2008 ist ein Modell zur Klassifizierung von Web-APIs hinsichtlich ihrer RESTfulness. REST steht hier repräsentativ für die Möglichkeiten des World Wide Webs als Tech-Stack für Webservices und das RMM misst, inwieweit ein Webservice von diesen Gebrauch macht.
Das RMM teilt Webservices dabei in vier Level ein, wobei Level 0 den geringsten Grad an RESTfullness vertritt und Level 3 den höchsten. Um deutsche Begrifflichkeiten zu verwenden kann man auch sagen, das RMM misst den REST-Reifegrad eines Webservices.
Level 0: Eine URI, ein HTTP-Verb
Level 0 beschreibt den geringsten Grad an RESTfulness. HTTP wird lediglich als Transportmittel verwendet, um zwei Komponenten über das Netzwerk miteinander sprechen zu lassen. Die gesamte Kommunikation läuft über eine URI unter Verwendung der gleichen HTTP-Methode, meist POST oder GET. XML-RPC- und SOAP-basierte Webservices sind oftmals auf Level 0 angesiedelt.
Webservices auf Level 0 weisen potenziell die höchste Komplexität auf. Viele verschiedene Inhalte werden an die gleiche URI geschickt. Es ist unklar, ob dadurch Daten verändert, gelöscht oder nur abgerufen werden, da immer die gleiche HTTP-Methode verwendet wird. Das Datenmodell, die Beziehungen verschiedener Daten zueinander und Aktionsmöglichkeiten generell gehen aus der Schnittstelle nicht hervor. Für die Verwendung der Schnittstelle muss die Dokumentation konsultiert werden, die ggf. auch in Form einer WSDL-Datei vorliegen kann.
Zieht man eine Analogie zur objektorientierten Programming, dann entspricht eine solche Schnittstelle einem Gottobjekt.
Level 1: Viele URIs, ein HTTP-Verb
Level 1 führt das Konzept von Ressourcen ein. Ein Endpunkt repräsentiert eine Ressource. Unterschiedliche Ressourcen werden durch unterschiedliche Endpunkte repräsentiert. Ressourcen des gleichen Typs unterscheiden sich hinsichtlich ihrer URIs über ihre IDs. Level 1 führt damit Objektidentität ein und weist Ähnlichkeiten zur objektorientierten Programmierung (OOP) auf. Ressourcen, die in einer hierarchischen Beziehung zueinander stehen werden auch durch eine Hierarchie in den URIs, ausgedrückt durch Slashes, repräsentiert.
Level 1 modularisiert eine Schnittstelle und reduziert damit die Komplexität der Logiken hinter den einzelnen Endpunkten. Eine neue Bestellung und ein neuer Kundendatensatz werden nun nicht mehr über die gleiche URI angelegt, sondern erhalten jeweils einen eigenen Endpunkt.
Level 2: Viele URIs, viele HTTP-Verben
Level 2 führt die Verwendung von HTTP-Methoden (auch: HTTP-Verben) ein. Die Verben GET, PUT und DELETE haben eine klare Bedeutung und sind an bekannte Rahmenbedingungen gebunden. Alle drei Methoden gelten als idempotent, womit für den Konsumenten der Schnittstelle eindeutig ist, was passiert wenn ein PUT oder DELETE auf die gleiche URI mehrfach ausgeführt wird. GET gilt außerdem als „safe“. Web-Crawler beispielsweise rufen beliebige URIs per HTTP-GET auf und gehen davon aus, dass dadurch keine wichtigen Daten manipuliert oder gelöscht werden.
| HTTP-Methode | sicher („safe“) | idempotent |
|---|---|---|
| GET | ja | ja |
| POST | nein | nein |
| DELETE | nein | ja |
| PUT | nein | ja |
| PATCH | nein | nein |
| HEAD | ja | ja |
| OPTIONS | ja | ja |
| TRACE | ja | ja |
Auch wenn Richardson meines Wissens in seinem Vortrag nicht darauf eingegangen ist, wird auch die Verwendung von HTTP-Statuscodes als ein Aspekt vom RMM Level 2 angesehen. Für einen SOAP-Service auf Level 0 ist es gängige Praxis, einen Fehler mit einem HTTP 200 (ok) zu beantworten und in der Antwort einen Fehlercode und -text zurückliefern. Das liegt auch daran, dass SOAP protokollagnostisch ist und neben HTTP beispielsweise auch über SMTP oder JMS abgebildet werden kann. REST hingegen ist eng an HTTP gekoppelt, wenn vielleicht auch nicht untrennbar. In jedem Fall ist es naheliegend im Fehlerfall zur Aktion passende HTTP-Statuscodes zu verwenden, zum Beispiel:
- HTTP 201 (created), wenn eine Ressource über ein POST oder PUT angelegt wurde
- HTTP 202 (accepted), wenn ein langlaufender Prozess über ein POST angestoßen wurde
- HTTP 204 (no content), wenn z.B. über ein DELETE eine Ressource gelöscht wurde und keine Antwort notwendig ist
- HTTP 409 (conflict), wenn ein Update über ein PUT fehlschlug, weil ein anderer Konsument die Ressource zwischenzeitlich verändert hatte
- HTTP 422 (unprocessable entity), wenn ein POST/PUT/DELETE z.B. wegen eines fachlichen Validierungsfehlers abgewiesen wurde
- und weitere…
Level 3: Hypermedia
Level 3 beschreibt den Einsatz von Hypermedia Controls, im Wesentlichen das unter dem etwas sperrigen Namen bekannte Prinzip Hypermedia as the Engine of Application State (HATEOAS), welches unter der Verlinkung in einem eigenen Beitrag beschrieben wird.
HATEOAS führt zu einer sehr losen Kopplung zwischen der Schnittstelle und seinen Konsumenten, da die API explorierbar wird und durch den Einsatz von Hypermedia selbst dokumentiert ist, es also nicht mehr erforderlich ist, in ein separates Dokument zu schauen und sich als Konsument die Links selbst zusammenzubauen.
Fazit
Die Umsetzung einer REST-Schnittstelle auf Level 0 oder Level 1 gleicht einem Anti-Pattern. REST ist nicht die Antwort auf alle Schnittstellen, aber wenn es REST sein soll, dann bitte zumindest RMM Level 2, da hiermit ein sauberes, modularisiertes API-Design ermöglicht wird. Die HTTP-Verben und Statuscodes repräsentieren oft verwendete Aktionen und Reaktionen, und sorgen damit für Einheitlichkeit und einen besseren Zugang zur Schnittstelle für Dritte.
Roy Fielding, der das REST-Paradigma entworfen hat, sieht HATEOAS als so elementaren Bestandteil von REST, dass sich eine Schnittstelle ohne HATEOAS gar nicht als REST-Schnittstelle bezeichnen sollen dürfte (Link zum Kommentar am Ende des Beitrags). Gleichzeitig ist die Verbreitung von HATEOAS im Internet meiner subjektiven Einschätzung nach eher gering und der Einsatz von HATEOAS erhöht die Komplexität in dem Service, der die Schnittstelle bereitstellt.
Ich persönlich würde den Einsatz von HATEOAS davon abhängig machen, ob die zusätzlichen Kosten den entstehenden Nutzen rechtfertigen. Dies ist zum Beispiel dann der Fall, wenn die Schnittstelle eine hohe Komplexität hat und es einem Client als Konsumenten der Schnittstelle durch den Einsatz von HATEOAS ermöglicht werden kann, auf hartkodierte URIs und die Abbildung von Geschäftslogik im Client zu verzichten.
Nimmt man sich das RMM zum Vorbild, sollte man sich außerdem im Klaren darüber sein, dass damit nur das API-Design bewertet wird, nicht aber die Modellierung und Prozesse hinter dieser Fassade.
- Vortrag von Leonard Richardson aus dem Jahr 2008 - Kommentar von Roy Fielding zu REST und HATEOAS