Schnittstellen über HTTP

Was ist eine REST-API?

Representational State Transfer

Eine REST-API ist eine Programmierschnittstelle über HTTP, die Daten als adressierbare Ressourcen anbietet, die Bearbeitung dieser Ressourcen über die HTTP-Methoden ausdrückt und dabei keinen Sitzungszustand auf dem Server hält.

Sobald zwei Systeme Daten austauschen sollen, landest du bei einer REST-Schnittstelle, und ob die Anbindung in Tagen oder in Wochen fertig ist, entscheidet ihr Zuschnitt.

KI-generiertDieses Bild wurde mit KI erzeugt · Yves Hoppe / KI / cmt

Geprägt von: Roy Fielding in seiner Dissertation im Jahr 2000
Baut auf: HTTP-Methoden, URLs und Statuscodes
Kernregel: Der Server merkt sich keinen Sitzungszustand
Beschrieben mit: OpenAPI

Ressourcen statt Aktionen

Der erste Schritt ist ein Wechsel der Denkweise: In der URL steht ein Ding, kein Vorgang. Also /rechnungen/17 und nicht /getRechnung?id=17. Was mit dem Ding passieren soll, sagt die Methode: GET liest, POST legt in einer Sammlung an, PUT ersetzt vollständig, PATCH ändert einzelne Felder, DELETE entfernt.

Zwei Eigenschaften dieser Methoden sind mehr als Formalie. GET muss sicher sein, darf also nichts verändern, sonst löst ein Proxy oder das Vorladen im Browser versehentlich Aktionen aus. PUT und DELETE müssen idempotent sein: Dieselbe Anfrage zweimal geschickt führt zum selben Endzustand, und genau darauf verlässt sich jede Wiederholung nach einem Zeitlimit.

Statuscodes sind die Fehlersprache

Der Statuscode ist der Teil der Antwort, den Zwischenschichten verstehen, ohne den Text zu lesen. 200 für Erfolg, 201 mit Location-Header nach dem Anlegen, 400 bei fehlerhafter Anfrage, 401 wenn die Anmeldung fehlt, 403 wenn sie da ist und trotzdem nicht reicht, 404 wenn es die Ressource nicht gibt, 409 bei einem Konflikt, 422 bei fachlich ungültigen Werten.

Der verbreitete Gegenentwurf, immer 200 zu senden und den Fehler in den Rumpf zu schreiben, macht Protokollierung, Wiederholungslogik und Caching blind. Ein Client kann dann nicht mehr entscheiden, ob sich ein zweiter Versuch lohnt.

Zustandslosigkeit und was daraus folgt

Zustandslos heißt, dass jede Anfrage alles mitbringt, was der Server zu ihrer Bearbeitung braucht, üblicherweise ein Token im Authorization-Header. Zwischen zwei Anfragen merkt sich der Server nichts über den Client. Das ist die Voraussetzung dafür, dass ein Lastverteiler die nächste Anfrage an eine beliebige Instanz geben kann.

Aus derselben Eigenschaft folgt, was REST im Alltag angenehm macht: Antworten auf GET lassen sich über URL und ETag zwischenspeichern, Bedingungen laufen über Standard-Header, und Paginierung sowie Filter gehören in die Query-Parameter statt in ausgedachte Extra-Endpunkte.

Dokumentation, die zum Code passt

Eine REST-Schnittstelle lebt von ihrer Beschreibung. Mit OpenAPI hältst du Pfade, Parameter, Rümpfe und Statuscodes maschinenlesbar fest, kannst daraus Clients erzeugen lassen und die Beschreibung im Test gegen die echten Antworten prüfen. Eine Doku, die nur im Wiki steht, veraltet zuverlässig.

KI-generiertDieses Bild wurde mit KI erzeugt · Yves Hoppe / KI / cmt

Nicht verwechseln

REST-API und was oft damit gleichgesetzt wird

REST-API gegen RPC

Bei einem entfernten Prozeduraufruf steht in der URL oder Nachricht ein Funktionsname, etwa berechneRabatt. Das ist nicht schlechter, nur anders: RPC bildet Vorgänge direkt ab, REST modelliert Zustände von Ressourcen.

REST-API gegen GraphQL

GraphQL hat einen Endpunkt, ein typisiertes Schema und lässt den Client die Felder bestimmen. Dafür entfällt das einfache HTTP-Caching, das bei REST über die URL gratis mitkommt.

REST-API gegen HATEOAS

Die Stufe, in der Antworten Links auf mögliche Folgeaktionen enthalten, gehört zur ursprünglichen Definition, wird aber selten umgesetzt. Die meisten Schnittstellen, die REST heißen, meinen Ressourcen plus HTTP-Verben.

KI-generiertDieses Bild wurde mit KI erzeugt · Yves Hoppe / KI / cmt

In der Praxis

Die meisten Anbindungen scheitern am Fehlerfall, nicht am Normalfall

In vielen Schnittstellen läuft der gute Fall sauber und alles andere kommt als Statuscode 200 mit einer Fehlermeldung im Rumpf zurück. Für den aufrufenden Code ist das die schlechteste Variante, weil er jede Antwort erst auspacken muss, um zu wissen, ob sie geglückt ist. Ein 404 für ein unbekanntes Objekt und ein 422 für eine unplausible Eingabe ersparen ihm diese Arbeit.

Der zweite Punkt ist die Wiederholung. Bricht die Verbindung nach einem POST ab, weiß der Aufrufer nicht, ob die Bestellung angelegt wurde. Ein mitgeschickter Schlüssel, unter dem der Server dieselbe Anfrage nur einmal ausführt, verhindert Doppelbuchungen, und dieser Schlüssel muss in der Schnittstelle vorgesehen sein, bevor der erste Kunde sie nutzt.

Verändern darfst du eine veröffentlichte Schnittstelle nur nach vorn. Ein Feld ergänzen ist unkritisch, ein Feld umbenennen bricht jeden Client, der es liest. Wer das ernst nimmt, legt schon beim ersten Release fest, wie eine zweite Version parallel laufen kann, statt später unter Zeitdruck zu improvisieren.

REST-API lernen

Wie eine Schnittstelle vom Entwurf bis zur Beschreibung mit OpenAPI entsteht, arbeiten die Trainings für moderne Webanwendungen an einem durchgehenden Beispiel durch.

Die Seite des Aufrufers, also Laden, Zwischenspeichern und Fehlerbehandlung im Browser, behandeln die Kurse zum Anbinden von Schnittstellen im Frontend .

Kurse, die REST-API behandeln

Häufige Fragen

Wie versioniere ich eine REST-API?

Am verbreitetsten ist ein Präfix im Pfad, etwa /v1/. Das ist grob, aber für alle sichtbar und in Logs sofort erkennbar. Feiner geht es über den Accept-Header, das kostet dafür Nachvollziehbarkeit. Wichtiger als die Methode ist, dass ergänzende Änderungen keine neue Version brauchen: Ein zusätzliches Feld darf niemanden brechen.

PUT oder PATCH?

PUT schickt die vollständige Ressource und ersetzt sie. PATCH überträgt nur die geänderten Felder. Wer PATCH anbietet, sollte festlegen, wie ein Feld geleert wird, sonst lässt sich ein einmal gesetzter Wert nie wieder entfernen.

Gehören Verben nie in die URL?

Für Vorgänge, die sich schlecht als Ressource fassen lassen, ist ein eigener Unterpfad üblich, etwa /rechnungen/17/stornierung per POST. Das bleibt lesbar, solange es die Ausnahme ist und nicht das Muster.

Persönlich für dich da