Konzept REST

In Ausnahmefällen kann auf die Einhaltung der Vorgabe zum Reifegrad (mindestens Level 2) verzichtet werden.

Prozessorientierte Aufrufe - Geschäftsvorfälle

Ein Ausnahmefall stellt die Abbildung von prozessorientierten Aufrufen dar, die häufig durch die Migration von bestehenden prozessorientierten Schnittstellen (z.B. RPC) entstanden sind. Die Abbildung auf eine ressourcenorientierte REST-Schnittstelle ist i.d.R. mit einer Neukonzeption der Anwendung unter einer ressourcenorientierten Denkweise verbunden. Der Aufwand für die Neukonzeption steht oft nicht im Verhältnis zum tatsächlichen (fachlichen) Nutzen. Aus diesem Grund dürfen prozessorientierte Aufrufe über einfache http-Aufrufe realisiert werden, die bis auf die Ressourcenorientierung und Verwendung der http-Verben, den übrigen Vorgaben des REST-Konzepts folgen. Diese http-Aufrufe entsprechen zwar nicht dem Reifegradmodell (Level 2), sind aber in diesem Ausnahmefall IsyFact-konform.

Wird über die Schnittstelle ein Geschäftsvorfall angestoßen, ist der Geschäftsvorfall in der URI zu adressieren:

Jede Ressource eines REST-Services ist über einen URI eindeutig adressierbar. Dieser Abschnitt legt Konventionen für den Aufbau der URIs fest.

Ressourcen repräsentieren Objekte und werden deshalb als Substantiv beschrieben. Die Bezeichnung muss möglichst einfach gewählt werden (z. B. der Name der Entität oder die Aufgabe der Ressource). Repräsentiert die Ressource eine Menge von Objekten, wird der Plural verwendet.

Der hierarchische Aufbau von Ressourcen ist explizit erwünscht:

Die folgenden Kapitel beschreiben, welche HTTP-Methoden zu unterstützen sind und welche Funktion sie besitzen. Die übrigen HTTP-Methoden werden nicht verwendet.

GET wird verwendet, um eine Ressource zu lesen. Die Ressource wird dabei nicht verändert, wodurch diese Methode idempotent ist.

Idempotenz beschreibt die Möglichkeit, den gleichen HTTP-Request mehrfach an die Schnittstelle senden zu können, ohne dass ein anderes Ergebnis erzielt wird als bei einem einzelnen Request.

POST wird verwendet, um eine neue Subressource innerhalb einer Ressource anzulegen. Es ist beim Erstellen von Datensätzen in den meisten Fällen das Mittel der Wahl, da das Backend hierbei die ID vergibt. Dadurch, dass die Datensätze mit neuen IDs angelegt werden, wird bei jedem weiteren senden des Requests ein neuer Datensatz angelegt und die Methode ist nicht idempotent. Des Weiteren muss POST für komplexe Suchen und Suchen mit datenschutzrelevanten Informationen verwendet werden, siehe Suche und Filterung mittels POST.

PUT wird verwendet, um eine Ressource zu ändern oder zu erstellen. Beim Ändern wird die gesamte Ressource mitgesendet und nicht nur der zu ändernde Teil wie bei PATCH. Ist die Ressource mit der gesendeten ID noch nicht vorhanden, wird diese durch PUT erstellt. Dies ist aber zu vermeiden, da der Client keine IDs vergeben soll. PUT ist, da immer die gesamte Ressource geändert wird, bzw. die ID beim Erstellen schon vorgegeben ist, idempotent. Deshalb ist PUT PATCH beim Aktualisieren vorzuziehen. In Abhängigkeit davon, ob eine Ressource geändert oder neu erstellt wurde, wird der entsprechende Response Code (200 OK bzw. 201 Created) zurückgegeben.

PATCH wird verwendet, um eine Ressource mit einer bestimmten ID zu ändern. Hierbei werden nur die Felder gesendet, die geändert werden sollen und nicht die ganze Ressource. Das kann bei Ressourcen mit beispielsweise einem Auto-Increment Feld dazu führen, dass bei mehreren Patches unterschiedliche Ergebnisse erzielt werden. Deswegen kann Patch idempotent sein, muss aber nicht.

DELETE wird verwendet zum Löschen einer Ressource. Da jede Ressource nur einmal gelöscht werden kann, ist diese Methode idempotent.

HEAD wird verwendet, um Meta-Informationen einer Ressource zu erhalten. Es gibt die gleichen Daten zurück wie GET nur ohne Response-Body und ist damit idempotent.

OPTIONS wird verwendet, um die von einer Ressource unterstützten Methoden anzuzeigen. Es ist idempotent, da nichts verändert wird.

Im Folgenden werden die HTTP-Statuscodes dargestellt, die zu verwenden sind.

Weitere Statuscodes sind in Abhängigkeit vom Fachverfahren möglich.

REST-Services können verschiedene Repräsentationen derselben Ressource anbieten. Diese Repräsentationen sind entweder textbasiert oder binär.

Liegt eine Ressource textbasiert vor, müssen ihre Repräsentationen, z. B. durch ein Schema, validierbar sein. Ebenso muss jede Repräsentation den gleichen, fachlichen Inhalt umfassen.

Liegt eine Ressource binär vor, muss sie bei direkten Abfragen (über GET) binär ohne weitere Veränderungen (z. B. Einbettung in eine textbasierte Form oder zusätzliche Encodings) zurückgegeben werden. Nicht erlaubt ist eine Einbettung einer binären Ressource in eine textbasierte Repräsentation (z. B. ein BASE64-encodiertes Bild in einem dafür geschaffenen JSON- oder XML-Dokument). Ist eine binäre Ressource Teil einer textbasierten Ressource, so wird eine Einbettung ebenfalls nicht empfohlen. Stattdessen sollte der URI der binären Ressource in der textbasierten Ressource enthalten sein, um sie bei Bedarf direkt abzufragen.

Diese Regel reduziert die Komplexität der internen Services und erhöht die Homogenität der Systemlandschaft. Ebenso fällt der Aufwand zur Pflege mehrerer, inhaltlich identischer Repräsentationsformen weg.

Die Kommunikation mit IT-Systemen außerhalb der Systemlandschaft sollte ebenfalls über eine festgelegte textbasierte Repräsentation geschehen. Hier sind jedoch gesetzliche Vorgaben, Rahmenbedingungen und die Anforderungen der externen Kommunikationspartner zu berücksichtigen.

Der Bereich Metadaten kann optional implementiert werden.

Zum Erhalten von Metadaten wird die HEAD-Methode verwendet. Die HEAD-Methode ist identisch zu GET, außer, dass sie keinen Response-Body zurückgibt.

Caching ist eine optionale Technik.

Wenn Caching eingesetzt werden soll, ist der Einsatz von ETags das Mittel der Wahl. ETags beschreiben die Version der Ressource, die angefragt wird. Ist der ETag im Header der Anfrage der gleiche, wie der ETag der gespeicherten Ressource, wird als Statuscode 304 zurückgegeben.

Zur Implementation wird in Spring der ShallowEtagHeaderFilter verwendet. Dieser reduziert allerdings nur die genutzte Netzwerk-Kommunikation, nicht aber die Rechenzeit im Server, da zum Vergleichen der ETags die Ressource geladen werden muss.

Weitere Caching-Methoden, die auch die Serverlast reduzieren, sind möglich.

Nach dem HATEOAS-Paradigma soll eine zurückgelieferte Ressourcen weiterführende URLs (vergleichbar mit HTML-Links) zu verwandten Ressourcen enthalten, anstelle die verwandten Ressourcen mit der angefragten Ressource zusammengeführt zu übermitteln.

Folgende Vorteile ergeben sich daraus:

Die letzten beiden Punkte führen direkt zu Fragestellungen des Schnittstellen- bzw. API-Designs:

Die letzten zwei Vorteile ergeben sich vor allem aus der Voraussetzung, dass der Client in der Regel die "zusätzlichen Daten" nicht benötigt, die nur über die URI als Referenz übermittelt werden. Werden diese zusätzlichen Daten nach jedem Aufruf der übergeordneten Ressource angefordert, werden zusätzliche technische Verarbeitungsschritte nötig (Client: Request für die neuen Daten aufbauen, versenden. Server: Anfrage & Berechtigung prüfen, Daten suchen, ggf. konvertieren, versenden,…).

Bei häufigen, parallelen Anfragen würde dieses Szenario dann einen hohen Overhead generieren. Hier ist im Einzelfall die Schnittstelle entsprechend dem gewünschten Trade-Off zu modellieren.

Die IsyFact legt folgende Technologien für die Umsetzung von REST-Schnittstellen (vgl. Tabelle 1) fest.

Das Spring Framework stellt seit Version 5 Spring Webflux als reaktive Alternative zu Spring MVC bereit.

Mit Webflux ist es möglich, reaktive REST APIs zu implementieren. Beim reaktiven Programmierparadigma geht es um die Reaktion auf Veränderungen (Observer Pattern), im Fall von REST APIs um die Reaktion auf gesendete Daten. Das ist hilfreich, wenn man große Datenmengen (z. B. Mediendateien oder größere Ergebnismengen aus einer Datenbankabfrage) über das REST API übertragen möchte. Die Daten werden dann in mehreren Paketen gesendet, der Empfänger reagiert jeweils auf den Erhalt eines Pakets.

Der Hauptvorteil von Webflux liegt aber im geringeren Ressourcenverbrauch auf der Server Seite. Webflux basiert auf einem Event-Loop Mechanismus, während Spring MVC auf Thread Pools basiert. Der Performance Vorteil von Webflux macht sich insbesondere bei vielen gleichzeiten Service-Aufrufen und/oder der Übertragung größerer Datenmengen bei einem Service-Aufruf bemerkbar.

Trotzdem empfiehlt die IsyFact grundsätzlich, Spring MVC für die Umsetzung von REST-Services einzusetzen. Die Vorteile des reaktiven Programmierparadigmas erfüllen sich nur, wenn alle Teile der Umsetzung entsprechend gestaltet sind. Dies ist aktuell nicht der Fall.

Für REST-Clients wiederum empfiehlt die IsyFact die Verwendung des WebClient anstatt des RestTemplate, da letzteres nicht mehr aktiv weiterentwickelt wird.

Für die Anbindung von Angular-Clients enthält der Baustein Angular eine entsprechende Komponente.

Alle auf IsyFact basierten Anwendungen müssen ihre REST-Schnittstellen mit der OpenAPI 3.0 Spezifikation beschreiben. Sowohl YAML als auch JSON sind als Format der Schnittstellendokumentation zulässig. Für die Erstellung der Schnittstellendokumentation ist grundsätzlich kein besonderes Tool erforderlich, ein Texteditor ist ausreichend. Das OpenAPI Format wird jedoch von diversen Entwicklungsumgebungen (z. B. IntelliJ) unterstützt, was die Bearbeitung erleichtert.

Die DTOs werden ebenfalls innerhalb der Schnittstellenbeschreibung schematisch beschrieben.

Der Code für die DTOs wird daraus generiert.

Innerhalb der Schnittstellenbeschreibung des Service werden die Schemata der DTOs üblicherweise als Referenz mittels #ref eingebunden. Die Referenz kann sich dabei auf eine Beschreibung innerhalb derselben Datei beziehen oder auch auf eine externe Datei. Die Datei kann dabei sowohl über einen Dateipfad als auch über eine URL adressiert werden.

Beispiel aus Swagger Petstore:

Wie bereits gesagt muss die formale Validierung der Daten vor der inhaltlichen Validierung im Anwendungskern stattfinden. Genau genommen müssen die Daten formal korrekt sein, bevor sie überhaupt in irgendeiner Weise weiter verarbeitet werden können. Daher ist die formale Prüfung der erste Schritt in der Verarbeitung von Daten und komplett unabhängig von der weiteren Verarbeitung.

Eine geeignete Methode zur Prüfung der Daten auf formale Korrektheit ist die Validierung gegen das vorhandene Schema der Schnittstellenbeschreibung. Atlassian bietet den Swagger Request Validator als freie Software an (Apache 2.0 Lizenz). Damit lassen sich HTTP Requests und Responses gegen eine OpenAPI bzw. Swagger Spezifikation prüfen, OpenAPI v3 wird dabei bereits unterstützt. Der Swagger Request Validator hat keine weiteren Abhängigkeiten und kann somit unabhängig von HTTP APIs oder Frameworks verwendet werden.

In diesem Abschnitt werden alle Aspekte zur Fehlerbehandlung in REST-Services beschrieben.

Bei der Fehlerbehandlung müssen zwei Varianten unterschieden werden: technische Fehler und fachliche Fehler.

Definition von technischen Exceptions: Service-Methoden deklarieren keine oder eine technische Exception. Die technische Exception muss für alle Service-Methoden einer Service-Schnittstelle gleich sein.

Definition von fachlichen Exceptions: Service-Methoden können beliebig viele fachliche Exceptions deklarieren. Diese können spezifisch für jede Service-Methode sein.

Übermittlung von Daten: Die Felder Ausnahme-ID, UUID und Fehlernachricht, wie in den Nutzungsvorgaben Fehlerbehandlung beschrieben, müssen stets übertragen werden. Weiterhin darf kein Stack-Trace übertragen werden.

Grundsätzlich sind die Vorgaben aus den Nutzungsvorgaben Fehlerbehandlung zu beachten. Im Anschluss folgen REST-Spezifische Regeln.

Technische Fehler werden in der HTTP-Response immer mit dem HTTP-Code 500 gesendet.

Fachlichen Fehlern muss ein entsprechend passender Fehlercode im Bereich 4xx zugeordnet werden.

Einheitliche Fehlermeldungen beschreibt den Inhalt einer Fehlermeldung.

Die Authentifizierung wird nach OAuth2 sichergestellt. Hierfür muss der Client mit jeder Nachricht einen Bearer Token mitsenden. Dieser wird im Request-Header mit dem Tag "Authorization" versehen. Im Sicherheitsbaustein wird das Token an den SecurityContextHolder weitergegeben. Dort werden die Daten ausgelesen und der Token wird auf Echtheit überprüft. Bei einer reinen Weitergabe greift die Bearer Propagation.

Um eine Klasse oder einzelne Methoden zu sichern, wird empfohlen, die @Secured Annotation von Spring Security in der Service-Schicht zu verwenden. Die Verwendung auf einzelnen Webcontroller Klassen/Methoden wird nicht empfohlen. Für Webcontroller ohne Service Schicht kann Request Level Autorisierung genutzt werden.

Generell ist das Konzept der Sicherheitsarchitektur zu beachten.

Eingehende und ausgehende Nachrichten sind an der Systemgrenze zu loggen. Für die Erstellung der Log-Einträge ist der Baustein Isy-Logging zu verwenden. Abweichungen zum Konzept von Isy-Logging sind im Folgenden aufgeführt.

Die IsyFact stellt zur Überwachung von Anwendungen den Baustein Überwachung bereit.

Die Grundlagen der Überwachung von IsyFact basierten Anwendungen werden im Konzept Überwachung beschrieben.

Detailliertere Informationen zur Konfiguration und zur Verwendung des Bausteins Überwachung findet man in den Nutzungsvorgaben Überwachung. Dieses Dokument beinhaltet auch das Kapitel "Informationen von Services". Dieses Kapitel beinhaltet eine Liste der zu überwachenden bzw. anzubietenden Informationen für die Services von Anwendungen. Die dort aufgelisteten Informationen müssen für jeden Service einzeln angeboten werden. Die dort beschriebenen Informationen zur Überwachung gelten in gleichem Maße auch für REST Services.

Versionierung kann auf verschiedene Weisen stattfinden.

Prinzipiell gilt es inkompatible API-Änderungen in einer REST-Schnittstelle zu vermeiden. Falls irgendwann eine inkompatible Änderung notwendig sein sollte, ist eine Versionierung in der URL zu verwenden.

Die Version steht immer vor dem Pfad der Ressource und beinhaltet ausschließlich die Major Version.