Schnittstellen über HTTP

Was ist eine REST-API?

Representational State Transfer

Eine REST-API ist eine Programmierschnittstelle, über die ein Programm per HTTP auf Daten und Funktionen eines anderen Systems zugreift. Die Daten stehen als Ressourcen unter eigenen URLs bereit, die HTTP-Methoden wie GET, POST oder DELETE sagen, was mit ihnen geschehen soll, und der Server merkt sich zwischen zwei Anfragen keinen Sitzungszustand.

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
Steht für
Representational State Transfer
Geprägt von
Roy Fielding in seiner Dissertation im Jahr 2000
Baut auf
URLs, HTTP-Methoden und Statuscodes
Verwechselt mit
SOAP, GraphQL und API allgemein

REST an einem Beispiel

REST ist kein Protokoll und kein Standard mit Prüfsiegel, sondern ein Architekturstil, also ein Satz von Regeln dafür, wie eine Schnittstelle über HTTP aufgebaut sein soll. Beschrieben hat ihn Roy Fielding, einer der Autoren der HTTP-Spezifikation, im Jahr 2000. Eine Schnittstelle, die sich an diese Regeln hält, heißt REST-API oder RESTful API.

Am einfachsten verstehst du das Prinzip an einer echten Anfrage. Ein Programm möchte die Daten von Kunde 4711 aus einem Shop-System lesen und schickt dafür eine GET-Anfrage an dessen Adresse. Der Server antwortet mit einem Statuscode und den Daten, hier im Format JSON:

GET /api/kunden/4711 HTTP/1.1
Host: shop.example.com
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{ "id": 4711, "name": "Muster GmbH", "ort": "Würzburg" }

Die Adresse /api/kunden/4711 bezeichnet die Ressource, also das Ding, um das es geht. Die Kombination aus Methode und Pfad, etwa GET /api/kunden/{id}, nennt man Endpunkt. Der Name Representational State Transfer beschreibt genau diesen Vorgang: Der Client bekommt nicht das Objekt selbst, sondern eine Darstellung seines aktuellen Zustands, und schickt bei Änderungen eine neue Darstellung zurück.

Ressourcen statt Aktionen: die HTTP-Methoden

Der wichtigste 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. Zwei Eigenschaften der Methoden sind dabei mehr als Formalie, nämlich ob sie sicher sind, also nichts verändern, und ob sie idempotent sind, also bei Wiederholung zum selben Endzustand führen.

MethodeZweckSicherIdempotent
GETRessource lesenjaja
POSTIn einer Sammlung anlegen oder Vorgang auslösenneinnein
PUTRessource vollständig ersetzenneinja
PATCHEinzelne Felder ändernneinnicht garantiert
DELETERessource entfernenneinja

Ändert ein GET doch etwas, löst ein Proxy oder das Vorladen im Browser versehentlich Aktionen aus. Idempotenz ist die Grundlage für jede automatische Wiederholung nach einem Zeitlimit: Ein zweimal geschicktes PUT oder DELETE richtet keinen zusätzlichen Schaden an, ein zweimal geschicktes POST legt dagegen unter Umständen zwei Bestellungen an.

Statuscodes: die Fehlersprache der Schnittstelle

Der Statuscode ist der Teil der Antwort, den Clients, Proxys und Monitoring verstehen, ohne den Inhalt zu lesen. Die erste Ziffer gibt die Klasse an: 2xx heißt Erfolg, 3xx Umleitung, 4xx ein Fehler auf Seiten des Aufrufers und 5xx ein Fehler auf dem Server. Die folgenden Codes deckt eine typische REST-API ab:

CodeBedeutungTypischer Fall
200OKLesen oder Ändern hat geklappt
201CreatedRessource angelegt, Adresse im Location-Header
204No ContentGelöscht, keine Daten in der Antwort
400Bad RequestAnfrage formal kaputt, etwa ungültiges JSON
401UnauthorizedAnmeldung oder Token fehlt
403ForbiddenAngemeldet, aber ohne Berechtigung
404Not FoundRessource gibt es nicht
409ConflictWiderspruch zum aktuellen Zustand
422Unprocessable ContentFormal korrekt, fachlich ungültig
429Too Many RequestsRatenlimit überschritten
500Internal Server ErrorUnerwarteter Fehler im Server

Für den Inhalt einer Fehlerantwort gibt es mit RFC 9457 („Problem Details for HTTP APIs“) ein standardisiertes JSON-Format mit Feldern wie type, title, status und detail. Wer es nutzt, erspart jedem Client das Rätselraten, wo in der Antwort die eigentliche Fehlermeldung steckt.

Die Regeln hinter REST

Fielding hat REST über eine Reihe von Bedingungen definiert. Eine Schnittstelle ist im strengen Sinn nur dann RESTful, wenn sie alle verbindlichen davon erfüllt:

  • Client und Server getrennt

    Oberfläche und Datenhaltung entwickeln sich unabhängig voneinander. Eine App und eine Website können dieselbe API nutzen.

  • Zustandslos

    Jede Anfrage bringt alles mit, was der Server zur Bearbeitung braucht, meist ein Token im Authorization-Header. Deshalb kann ein Lastverteiler die nächste Anfrage an jede beliebige Serverinstanz geben.

  • Cache-fähig

    Antworten sagen selbst, ob und wie lange sie zwischengespeichert werden dürfen, etwa über Cache-Control und ETag.

  • Einheitliche Schnittstelle

    Ressourcen haben eindeutige Adressen, werden über Darstellungen bearbeitet, und Antworten beschreiben sich selbst. Dazu gehört auch HATEOAS: Antworten enthalten Links auf mögliche Folgeaktionen.

  • Schichtensystem

    Zwischen Client und Server dürfen Proxys, Gateways oder Caches sitzen, ohne dass der Client das merkt.

  • Code on Demand (optional)

    Der Server darf ausführbaren Code mitliefern, etwa JavaScript. Diese Bedingung ist als einzige freiwillig.

In der Praxis erfüllen die meisten Schnittstellen, die sich REST nennen, nur einen Teil davon: Ressourcen, HTTP-Methoden, Statuscodes und Zustandslosigkeit. HATEOAS setzen nur wenige um. Das ist kein Makel, solange klar ist, was die Schnittstelle zusagt. Paginierung, Filter und Sortierung gehören übrigens in Query-Parameter wie ?seite=2&status=offen, nicht in eigene Endpunkte.

Beschreibung mit OpenAPI

Eine REST-Schnittstelle lebt von ihrer Beschreibung. Der verbreitete Standard dafür ist die OpenAPI Specification, früher unter dem Namen Swagger bekannt. Darin hältst du Pfade, Parameter, Datenstrukturen und Statuscodes maschinenlesbar in YAML oder JSON fest.

Aus dieser Datei erzeugen Werkzeuge eine interaktive Dokumentation wie Swagger UI, Client-Bibliotheken für verschiedene Programmiersprachen und Testfälle, die prüfen, ob die echten Antworten zur Beschreibung passen. Eine Doku, die nur im Wiki steht, veraltet dagegen 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 SOAP

SOAP ist ein Protokoll mit festem XML-Umschlag, das meist alle Aufrufe per POST an einen einzigen Endpunkt schickt und die Schnittstelle in einer WSDL-Datei beschreibt. Es ist strenger und schwergewichtiger als REST und begegnet dir vor allem in älteren Unternehmens- und Behördensystemen.

REST-API gegen GraphQL

GraphQL hat einen Endpunkt und ein typisiertes Schema, und der Client bestimmt in der Abfrage selbst, welche Felder er haben will. Dafür entfällt das einfache HTTP-Caching, das bei REST über die URL mitkommt.

REST-API gegen RPC und gRPC

Bei einem entfernten Prozeduraufruf steht in der Nachricht ein Funktionsname, etwa berechneRabatt. gRPC ist eine moderne Variante mit binärem Format und HTTP/2, beliebt zwischen internen Diensten. RPC bildet Vorgänge ab, REST modelliert Zustände von Ressourcen.

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.

Häufige Fragen

Was ist der Unterschied zwischen einer API und einer REST-API?
API ist der Oberbegriff für jede Programmierschnittstelle, auch für die Funktionen einer Bibliothek oder eines Betriebssystems. Eine REST-API ist eine bestimmte Art davon: Sie läuft über HTTP und folgt dem REST-Architekturstil. Jede REST-API ist also eine API, aber nicht umgekehrt.
Muss eine REST-API JSON liefern?
Nein. REST legt kein Datenformat fest, der Client fragt über den Accept-Header an, welche Darstellung er möchte. JSON hat sich durchgesetzt, weil es kompakt ist und jede Programmiersprache es lesen kann, XML oder CSV sind aber genauso zulässig.
Wie wird eine REST-API abgesichert?
Die Verbindung läuft immer über HTTPS. Für die Anmeldung schickt der Client bei jeder Anfrage einen Nachweis mit, meist ein Token nach OAuth 2.0 oder bei einfachen Anbindungen einen API-Schlüssel. Fehlt der Nachweis, antwortet der Server mit 401, reicht die Berechtigung nicht, mit 403.
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 einen Header, das kostet dafür Nachvollziehbarkeit beim Debuggen.
Gehören Verben nie in die URL?
Für Vorgänge, die sich schlecht als Ressource fassen lassen, ist ein eigener Unterpfad üblich, etwa POST /rechnungen/17/stornierung. Das bleibt lesbar, solange es die Ausnahme ist und nicht das Muster.

Passt thematisch dazu

Bevor die erste Anwendung angebunden wird, lohnt der Blick darauf, wie du Fehlerfälle, Rechte und Grenzwerte einer API testest.

Auf der Seite des Aufrufers lohnt es sich, API-Antworten im Frontend typsicher zu prüfen, statt der Beschreibung blind zu vertrauen.

Persönlich für dich da

Deine Ansprechpartner

Du willst das Thema nicht nur nachschlagen, sondern anwenden können? Wir beraten dich persönlich und kostenlos.

Yves Hoppe

Yves Hoppe

Weiterbildung & Beratung

Ordnet mit dir ein, welcher Kurs zu deinem Vorwissen passt.

Norbert Jansen

Norbert Jansen

Beratung & Inhouse

Plant Inhouse-Trainings, die an euren eigenen Daten und Abläufen ansetzen.

REST-API im Kurs statt im Lexikon

Nachschlagen bringt dich bis zum Verstehen. Anwenden lernst du an echten Aufgaben.