REST API Design: Ressourcen, Versionierung, Fehlercodes, Beispiele.
REST API Design: Wie man Schnittstellen baut, die auch in 2 Jahren noch Sinn ergeben
Eine schlecht designte API zu verbessern ist aufwändig. Sie erstmal richtig zu machen – das ist die Investition.
Was eine gute REST API ausmacht
Konsistenz. Ein Entwickler, der einen Endpoint verstanden hat, sollte alle anderen vorhersagen können. Naming, Ressourcenstruktur, Fehlercodes, Paginierung – das sollte überall gleich funktionieren.
Das klingt offensichtlich. Aber in der Praxis wachsen APIs organisch: Ein Endpoint nach dem anderen, gebaut von verschiedenen Personen, zu verschiedenen Zeiten, ohne gemeinsame Konvention.
Ressourcen, nicht Aktionen
REST ist ressourcenorientiert. /users/{id} – gut. /getUser?userId=123 – nicht REST. HTTP-Methoden definieren die Aktion: GET für lesen, POST für erstellen, PUT/PATCH für aktualisieren, DELETE für löschen.
Wer Aktionen braucht, die nicht in dieses Schema passen, kann RPC-artige Endpoints als Ausnahme definieren – aber sparsam.
Status Codes richtig einsetzen
200 OK für erfolgreiche GET-Anfragen. 201 Created nach POST. 204 No Content für DELETE ohne Response-Body. 400 für Client-Fehler (falsche Eingabe). 401 für fehlende Auth. 403 für fehlende Berechtigung. 404 für nicht gefundene Ressource. 500 für Serverfehler.
Und: Fehler-Responses mit Machine-readable Format, nicht nur einer Fehlermeldung als String.
Versionierung von Anfang an
API-Versionierung ist Pflicht. /v1/, /v2/ im Pfad ist der pragmatische Weg. Header-based Versionierung ist eleganter, aber weniger verbreitet. Wichtig: Breaking Changes immer in einer neuen Version.
Dokumentation als Teil der Entwicklung
OpenAPI/Swagger Spec von Anfang an führen – nicht nachträglich. So gibt es immer eine aktuelle Spec, aus der Mocking, Client-Generierung und Dokumentation entstehen können.
Checkliste REST API Design
Konsistentes Naming (Plurale, lowercase, kebab-case)
HTTP-Methoden korrekt eingesetzt
Status Codes semantisch korrekt
Fehler-Responses maschinenlesbar (Problem Details RFC 7807)
Versionierung implementiert
OpenAPI Spec vorhanden und aktuell
Paginierung für alle List-Endpoints
API Review oder API Design von Grund auf?
markom.digital entwirft REST APIs, die konsistent und gut dokumentiert sind – und prüft bestehende APIs auf Verbesserungspotenzial.
