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.
| Methode | Zweck | Sicher | Idempotent |
|---|---|---|---|
| GET | Ressource lesen | ja | ja |
| POST | In einer Sammlung anlegen oder Vorgang auslösen | nein | nein |
| PUT | Ressource vollständig ersetzen | nein | ja |
| PATCH | Einzelne Felder ändern | nein | nicht garantiert |
| DELETE | Ressource entfernen | nein | ja |
Ä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:
| Code | Bedeutung | Typischer Fall |
|---|---|---|
| 200 | OK | Lesen oder Ändern hat geklappt |
| 201 | Created | Ressource angelegt, Adresse im Location-Header |
| 204 | No Content | Gelöscht, keine Daten in der Antwort |
| 400 | Bad Request | Anfrage formal kaputt, etwa ungültiges JSON |
| 401 | Unauthorized | Anmeldung oder Token fehlt |
| 403 | Forbidden | Angemeldet, aber ohne Berechtigung |
| 404 | Not Found | Ressource gibt es nicht |
| 409 | Conflict | Widerspruch zum aktuellen Zustand |
| 422 | Unprocessable Content | Formal korrekt, fachlich ungültig |
| 429 | Too Many Requests | Ratenlimit überschritten |
| 500 | Internal Server Error | Unerwarteter 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
REST-API und was oft damit gleichgesetzt wird
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.
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.
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
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
- REST Services mit OpenAPI und Swagger für Entwickler
- FastAPI-Schulung: REST-APIs mit Python entwickeln
- REST APIs mit Spring Boot
- Moderne REST APIs mit Node.js, Express und MongoDB
- Postman-Schulung: API-Abfragen / Testing für REST-APIs
- OWASP API Security Training: REST-API sicher testen
Weitere Kurse aus diesem Bereich
Häufige Fragen
Was ist der Unterschied zwischen einer API und einer REST-API?
Muss eine REST-API JSON liefern?
Wie wird eine REST-API abgesichert?
Wie versioniere ich eine REST-API?
Gehören Verben nie in die URL?
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.
Deine Ansprechpartner
Du willst das Thema nicht nur nachschlagen, sondern anwenden können? Wir beraten dich persönlich und kostenlos.
Yves Hoppe
Weiterbildung & Beratung
Ordnet mit dir ein, welcher Kurs zu deinem Vorwissen passt.
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.
Verwandte Begriffe
Alle Begriffe im Glossar