REST APIs

Was ist REST?

REST, oder Representational State Transfer, ist ein Architekturstil für das Design von HTTP APIs. Anstatt eigene Befehle zu erfinden, modellieren Sie Ihren Domain-Bereich als Ressourcen und nutzen die bereits von HTTP definierten Methoden, um mit diesen zu interagieren. Ein POST /posts erstellt einen Post, GET /posts/42 liest einen aus, PATCH /posts/42 aktualisiert ihn und DELETE /posts/42 löscht ihn.

Der große Vorteil ist die Vertrautheit. Jeder HTTP Client, Proxy, Cache und jedes Tool versteht bereits die Methoden, Statuscodes und Header. Wenn Sie sich an die Konventionen halten, können Clients vorhersagen, wie sich Ihre API verhält, ohne ein spezielles Handbuch lesen zu müssen.

Ressourcen und URIs

Ressourcen sind die Substantive Ihrer API. Verwenden Sie Pluralformen für Collections und identifizieren Sie einzelne Elemente über eine id.

GET    /posts
POST   /posts
GET    /posts/42
PUT    /posts/42
PATCH  /posts/42
DELETE /posts/42

• Verwenden Sie Substantive, keine Verben. Die Methode ist das Verb.
• Verwenden Sie konsistent Pluralformen für Collection-Namen.
• Schreiben Sie URLs kleingeschrieben mit Bindestrichen, nicht mit Unterstrichen oder in camelCase.
• Nutzen Sie Nesting nur, wenn die Beziehung essenziell ist, wie bei /posts/42/comments.
• Geben Sie das Format nicht im Pfad an; verwenden Sie stattdessen den Accept-Header.

Tiefes Nesting wird schnell unübersichtlich. /users/1/posts/2/comments/3 ist schwer aufzubauen und zu dokumentieren; bevorzugen Sie /comments/3 und lassen Sie die Clients filtern.

Methoden und ihre Semantik

Jede Methode hat definierte Semantiken, auf die sich Clients und die Infrastruktur verlassen.

Safe bedeutet, dass der Zustand nicht verändert wird; idempotent bedeutet, dass eine wiederholte Ausführung denselben Effekt hat wie eine einmalige Ausführung. Ändern Sie niemals Daten mit GET, da Clients, Crawler und Caches GET-Requests beliebig oft ausführen können.

Status-Codes

Geben Sie den Code zurück, der dem tatsächlichen Ergebnis entspricht. Dies ist der Teil, auf den sich Clients am stärksten verlassen.

• 200 OK — Erfolg mit Body.
• 201 Created — eine Ressource wurde erstellt; fügen Sie einen Location-Header hinzu.
• 204 No Content — Erfolg ohne Body, häufig bei DELETE.
• 400 Bad Request — fehlerhafte Anfrage.
• 401 Unauthorized — Authentifizierung fehlt oder ist ungültig.
• 403 Forbidden — authentifiziert, aber nicht berechtigt.
• 404 Not Found — Ressource nicht gefunden.
• 409 Conflict — Zustandskonflikt, zum Beispiel ein Duplikat.
• 422 Unprocessable Entity — syntaktisch korrekt, aber die Validierung ist fehlgeschlagen.
• 429 Too Many Requests — Rate Limit erreicht; fügen Sie Retry-After hinzu.
• 500 Internal Server Error — unerwarteter Serverfehler.

Die Rückgabe von 200 mit { "success": false } verbirgt Fehler vor Clients, Caches und Monitoring-Systemen und zwingt jeden Client dazu, ein eigenes Error-Handling zu implementieren.

Collections: Filtern, Sortieren und Pagination

Collections benötigen eine konsistente Abfragesprache.

GET /posts?status=published&sort=-createdAt&limit=20&cursor=abc123

• Filtern mit field=value und wiederholten Keys für OR.
• Sortieren mit sort=field oder sort=-field für absteigende Reihenfolge.
• Pagination mit limit und cursor (oder page und perPage).
• Feldauswahl mit fields=id,title, wenn Clients weniger Daten benötigen.
• Suche über einen dedizierten q-Parameter.

Bevorzuge Cursor-Pagination für große oder sich häufig ändernde Datensätze und gib immer den nächsten Cursor in der Antwort zurück, damit Clients paginieren können, ohne raten zu müssen.

{
  "data": [{ "id": "42", "title": "Hello" }],
  "pagination": { "nextCursor": "abc123", "hasMore": true }
}

Repräsentationen und Antworten

Antworten sind Repräsentationen von Ressourcen. JSON ist hierbei der Standard mit einer stabilen Struktur.

{
  "id": "42",
  "title": "Hello",
  "createdAt": "2026-09-15T10:00:00Z"
}

• Verwenden Sie konsistent entweder camelCase oder snake_case, aber nicht beides.
• Verwenden Sie für Datumsangaben Strings im ISO 8601 Format.
• Verwenden Sie stabile IDs als Strings, falls Clients die Präzision von Zahlen überschreiten könnten.
• Umschließen Sie Collections mit data und pagination, aber geben Sie einzelne Ressourcen direkt zurück.
• Unterstützen Sie Accept und setzen Sie Content-Type korrekt.

Zustandslosigkeit und Caching

Jeder Request sollte alle Informationen enthalten, die für seine Verarbeitung benötigt werden: die URL, die Methode, Header und den Body. Verlassen Sie sich nicht auf den Serverspeicher zwischen einzelnen Requests – genau das ermöglicht es Ihnen, viele Instanzen hinter einem Load Balancer zu betreiben.

Da GET-Requests sicher sind und die Antworten in sich geschlossen sind, funktioniert REST hervorragend mit HTTP-Caching. Setzen Sie Cache-Control und Validatoren wie ETag bei cachebaren Ressourcen, wie im HTTP-Guide beschrieben.

Fehler

Verwenden Sie überall ein einheitliches Fehlerformat und dokumentieren Sie dieses.

{
  "error": {
    "code": "validation_error",
    "message": "Title is required",
    "details": [{ "field": "title", "issue": "required" }]
  }
}

Ein maschinenlesbarer code ermöglicht es Clients, entsprechende Logik-Zweige auszuführen, eine message kann sicher an Benutzer angezeigt werden und details hilft Formularen dabei, entsprechende Felder hervorzuheben. Kombinieren Sie dies mit dem passenden Statuscode.

Best Practices

• Modellieren Sie Ressourcen mit Substantiven und lassen Sie Methoden die Aktionen ausdrücken.
• Geben Sie den spezifischsten Statuscode zurück, den Sie verwenden können.
• Versionieren Sie die API, bevor es notwendig wird, und dokumentieren Sie diese (siehe API Versioning).
• Implementieren Sie eine Paginierung für jede Collection und begrenzen Sie diese auf limit.
• Validieren Sie Eingaben und geben Sie strukturierte Fehler zurück.
• Verwenden Sie durchgehend eine konsistente Benennung und Schreibweise.
• Cachen Sie sichere GET-Antworten mit expliziten Headern.
• Implementieren Sie Rate Limiting und Authentifizierung (siehe Rate Limiting).

Häufige Fehler

• Verb-basierte URLs, die HTTP-Methoden duplizieren.
• Rückgabe von 200 bei Fehlern.
• Unbegrenzte Collections ohne Pagination.
• Inkonsistente Groß-/Kleinschreibung, Datumsformate oder Fehlerstrukturen.
• Tiefe Verschachtelungen, die unwartbar werden.
• Mutation des State bei GET.
• Breaking Changes für Clients durch stillschweigende Änderung der Response-Strukturen.

Wie geht es weiter?

REST ist der Standardweg, um ein Backend bereitzustellen. Vertiefen Sie Ihr Wissen im HTTP-Guide, dokumentieren Sie Ihre Schnittstellen mit OpenAPI, entwickeln Sie diese sicher mithilfe von API Versioning weiter und schützen Sie Ihr System durch Rate Limiting. Vergleichen Sie dieses Modell mit GraphQL, wenn Ihre Clients mehr Flexibilität benötigen.