Wie gestalten Sie eine REST-API richtig? Prinzipien und Best Practices

Warum gutes API-Design entscheidend ist

REST (Representational State Transfer) ist der heute dominante Architekturstil für Web-APIs. Kein Standard, kein Protokoll, sondern ein Architekturmuster mit sechs Prinzipien, von denen in der Praxis vor allem vier eine Rolle spielen: Stateless, Client-Server-Trennung, einheitliche Schnittstelle und Cachability.

Eine API ist, einmal veröffentlicht, schwer zu ändern — andere Teams, Systeme und externe Partner bauen darauf auf. Ein schlechter Endpunkt-Name, eine inkonsistente Datenstruktur oder ein falsch verwendeter Statuscode sind Probleme, die sich über Jahre multiplizieren. Breaking Changes, also rückwärts-inkompatible Änderungen, erzwingen koordinierte Updates bei allen Consumern und sind einer der häufigsten Auslöser für Produktionsfehler. Gute APIs dagegen ermöglichen schnelle Integration, reduzieren Rückfragen zwischen Teams und machen Systeme leicht erweiterbar.

URL-Design und HTTP-Methoden

Das Fundament einer REST-API sind Ressourcen-URLs und HTTP-Methoden. Eine Ressource ist ein konzeptionelles Objekt — ein Nutzer, eine Bestellung, ein Produkt. URLs sollen Ressourcen benennen, keine Aktionen. Der häufigste Anfängerfehler ist action-basiertes URL-Design (/getUser, /createOrder, /deleteProduct) — das ist RPC-Stil, kein REST.

Korrektes URL-Design verwendet Substantive im Plural: /users für die Sammlung, /users/42 für einen spezifischen Nutzer, /users/42/orders für dessen Bestellungen. Verschachtelungen sollten maximal zwei Ebenen tief gehen.

Die HTTP-Methoden definieren die Aktion: GET liest Daten ohne Seiteneffekte, POST erstellt neue Ressourcen, PUT ersetzt eine Ressource vollständig, PATCH aktualisiert einzelne Felder, DELETE löscht eine Ressource. GET und DELETE sind idempotent — beliebig oft wiederholbar mit demselben Ergebnis. PUT ist ebenfalls idempotent, POST hingegen nicht: mehrfaches Senden erstellt mehrere Ressourcen.

API-Versionierung sollte von Anfang an eingeplant werden. Der verbreitetste Ansatz ist URL-basiert (/api/v1/users, /api/v2/users) — pragmatisch und in der Praxis die häufigere Wahl. Alternativ lässt sich die Version im HTTP-Header übertragen, was sauberer, aber schwerer zu testen ist.

HTTP-Statuscodes korrekt verwenden

• 200 OK: Erfolgreiche GET-, PUT- oder PATCH-Anfrage mit Antwort-Body
• 201 Created: Ressource erfolgreich erstellt (nach POST), mit Location-Header
• 204 No Content: Erfolgreiche Anfrage ohne Antwort-Body (z. B. nach DELETE)
• 400 Bad Request: Ungültige Anfrage-Syntax oder fehlende Pflichtfelder
• 401 Unauthorized: Keine oder ungültige Authentifizierung
• 403 Forbidden: Authentifiziert, aber keine Berechtigung für diese Ressource
• 404 Not Found: Ressource existiert nicht
• 409 Conflict: Konflikt mit aktuellem Ressourcenzustand
• 422 Unprocessable Entity: Valide Syntax, aber fehlgeschlagene Business-Validierung
• 429 Too Many Requests: Rate Limit überschritten
• 500 Internal Server Error: Unerwarteter Serverfehler

Konsistenz bei Request und Response

1. Konsistente Datenstrukturen in allen Endpunkten: Ein Wrapper-Objekt wie { data: {...}, meta: {pagination}, errors: [] } sorgt für Einheitlichkeit. Feldnamen sollten überall gleich geschrieben werden — camelCase oder snake_case, nie gemischt. 2. Pagination für Listen-Endpunkte: Kein Listen-Endpunkt sollte unbegrenzte Ergebnisse liefern. Offset-basierte Pagination (?page=2&limit=25) ist einfach, hat aber Schwächen bei großen Datensätzen; Cursor-basierte Pagination ist robuster und Standard bei großen APIs. 3. Filtering und Sorting als Query-Parameter: Filter gehören als Query-Parameter in die URL (/users?status=active&role=admin), Sortierung lässt sich mit ?sort=created_at&order=desc lösen — konsistent über alle Endpunkte hinweg. 4. Aussagekräftige Fehlermeldungen: Ein 400-Fehler mit leerem Body ist wertlos. Gute Fehlermeldungen enthalten einen maschinenlesbaren Fehlercode, eine menschenlesbare Beschreibung und bei Validierungsfehlern die betroffenen Felder.

Authentifizierung, Dokumentation und Sicherheit

Jede nicht öffentliche API benötigt Authentifizierung. API-Keys werden im HTTP-Header mitgeschickt und sind gut für Server-zu-Server-Kommunikation geeignet — sie sollten nie in URLs erscheinen und immer über HTTPS laufen. OAuth 2.0 ist das Standard-Framework für delegierte Autorisierung, etwa wenn ein Nutzer einer Drittanbieter-Anwendung Zugriff gewährt, ohne sein Passwort preiszugeben — für die meisten Projekte empfiehlt sich dafür ein etablierter Identity Provider. JWT (JSON Web Tokens) sind selbst-enthaltende, signierte Tokens: Der Server braucht keine Session-Datenbank, dafür lassen sich JWTs nicht direkt widerrufen — kurze Access-Token-Laufzeiten und Refresh-Tokens sind die übliche Lösung.

OpenAPI/Swagger ist der Industriestandard für API-Dokumentation: Eine Spezifikation beschreibt alle Endpunkte, Parameter und Schemata maschinenlesbar, Swagger UI und ReDoc generieren daraus interaktive Dokumentation. Die Spezifikation sollte aus dem Code generiert werden, nicht manuell gepflegt — manuelle Dokumentation ist immer veraltet.

Rate Limiting schützt vor Überlastung: Ein Limit pro Client und Zeitfenster (etwa 1.000 Requests pro Stunde) mit Statuscode 429 bei Überschreitung. Sicherheit umfasst außerdem korrekt konfiguriertes CORS, serverseitige Input-Validierung gegen SQL-Injection und XSS, Prepared Statements bei Datenbankzugriffen und ausnahmslos HTTPS für die gesamte API-Kommunikation.