EMZETT.
Login

Emzett Wiki

REST-API-Design: Ressourcen, Methoden und Statuscodes

Properties1
tagsglossar, web, api

2 Min. Lesezeit

REST-API-Design: Ressourcen, Methoden und Statuscodes

Kurz: Grundregeln, wie man eine Web-Schnittstelle so entwirft, dass sie vorhersehbar ist: Dinge als Ressourcen, HTTP-Methoden für Aktionen, Statuscodes für Ergebnisse.

Genauer: REST ist ein Architekturstil für Web-Schnittstellen. Statt eigener Verben wie /getUser oder /deleteOrder nutzt man die vorhandenen Möglichkeiten von HTTP. Wer die Regeln kennt, kann fremde Schnittstellen schnell verstehen und eigene so bauen, dass sie wenig Erklärung brauchen.

Im Detail

Ressourcen in URLs

Eine URL benennt ein Ding (Substantiv, meist Mehrzahl), nicht eine Handlung:

GET    /kunden            Liste der Kunden
GET    /kunden/42         ein Kunde
POST   /kunden            neuen Kunden anlegen
PUT    /kunden/42         Kunde ersetzen
PATCH  /kunden/42         Kunde teilweise ändern
DELETE /kunden/42         Kunde löschen
GET    /kunden/42/bestellungen   untergeordnete Ressource

Methoden und ihre Eigenschaften

GET liest und verändert nichts (sicher). GET, PUT und DELETE sind idempotent: Mehrfaches Ausführen ergibt denselben Zustand wie einmal. POST ist es nicht, ein zweiter Aufruf kann zwei Kunden anlegen. Deshalb sind für kritische POST-Anfragen Schlüssel zur Wiederholungssicherheit üblich.

Statuscodes

  • 200 OK, 201 Created (mit Location-Header), 204 No Content.
  • 400 Bad Request (fehlerhafte Eingabe), 401 Unauthorized (nicht angemeldet), 403 Forbidden (keine Berechtigung), 404 Not Found, 409 Conflict, 422 Unprocessable Content, 429 Too Many Requests.
  • 500 und höher: Fehler auf dem Server. Fehlerantworten sollten ein einheitliches Format mit verständlicher Meldung haben, zum Beispiel nach RFC 9457 (Problem Details).

Weitere Hinweise

Für Listen gehören Paginierung, Filter und Sortierung als Abfrageparameter dazu (?seite=2&sort=name). Daten werden meist als JSON mit durchgängigen Namen und ISO-8601-Datum geliefert. Beschreibe die Schnittstelle in einer Spezifikation wie OpenAPI. Reines REST hat Grenzen, etwa bei sehr verschachtelten Abfragen, wofür GraphQL oder RPC-Stile passender sein können.

Siehe auch: APIs, Paginierung

Backlinks