API-Design: REST-APIs richtig gestalten – Prinzipien, Fehler und Best Practices

Eine API (Application Programming Interface) ist eine definierte Schnittstelle, über die Softwaresysteme miteinander kommunizieren. REST (Representational State Transfer) ist der heute dominante Architekturstil für Web-APIs. REST ist kein Standard und 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.

Warum ist gutes API-Design so wichtig? Weil eine API, einmal veröffentlicht, schwer zu ändern ist. Andere Teams, andere Systeme und externe Partner bauen auf dieser Schnittstelle 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 in der Praxis 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. Das ist nicht nur ein technischer Vorteil, sondern ein direkter wirtschaftlicher Faktor: Jede Stunde, die ein Entwickler mit dem Verständnis einer schlechten API verbringt, kostet bares Geld.

Das Fundament einer REST-API sind die Ressourcen-URLs und die 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 die Bestellungen dieses Nutzers. Verschachtelungen sollten maximal zwei Ebenen tief gehen – tiefere Hierarchien werden unlesbar und schwer handhabbar.

Die HTTP-Methoden definieren die Aktion auf der Ressource: GET liest Daten (ohne Seiteneffekte), POST erstellt neue Ressourcen, PUT ersetzt eine Ressource vollständig, PATCH aktualisiert einzelne Felder einer Ressource, DELETE löscht eine Ressource. GET und DELETE sind idempotent – sie können beliebig oft wiederholt werden und liefern dasselbe Ergebnis. PUT ist ebenfalls idempotent, POST hingegen nicht: Mehrfaches Senden eines POST-Requests erstellt mehrere Ressourcen.

API-Versionierung sollte von Anfang an eingeplant werden. Der verbreitetste Ansatz ist die URL-basierte Versionierung: /api/v1/users, /api/v2/users. Alternativ kann die Version im HTTP-Header (Accept: application/vnd.api+json;version=2) übertragen werden – das ist sauberer, aber schwerer zu testen. URL-Versionierung ist pragmatischer und in der Praxis die häufigere Wahl.

Jede API, die nicht öffentlich ist, benötigt Authentifizierung. Die drei häufigsten Mechanismen sind API-Keys, OAuth 2.0 und JWT (JSON Web Tokens) – und sie haben unterschiedliche Einsatzzwecke.

API-Keys sind einfache Tokens, die im HTTP-Header mitgeschickt werden: Authorization: Bearer mein-api-key. Sie sind einfach zu implementieren und gut für Server-zu-Server-Kommunikation geeignet, bei der ein definierter Client mit bekannten Berechtigungen die API nutzt. API-Keys sollten nie in URLs erscheinen (sie landen dann in Server-Logs) und immer über HTTPS übertragen werden.

OAuth 2.0 ist das Standard-Framework für delegierte Autorisierung. Es ermöglicht, dass ein Nutzer einer Drittanbieter-Anwendung Zugriff auf seine Ressourcen gewährt, ohne sein Passwort preiszugeben. Der Authorization Code Flow ist der sicherste und für Web-Apps empfohlene Grant Type. OAuth 2.0 ist komplex in der Implementierung – für die meisten Projekte empfiehlt sich ein etablierter Identity Provider wie Keycloak, Auth0 oder AWS Cognito.

JWT (JSON Web Tokens) sind selbst-enthaltende Tokens, die Claims als Base64-encodiertes JSON enthalten und kryptografisch signiert sind. Der Vorteil: Der Server muss keine Session-Datenbank pflegen, weil alle nötigen Informationen im Token stehen. Der Nachteil: JWTs können nicht direkt widerrufen werden – ein kompromittiertes Token ist bis zu seiner Ablaufzeit (exp-Claim) gültig. Refresh-Tokens mit kurzen Access-Token-Laufzeiten (15 Minuten) und Token-Blacklists sind die übliche Lösung.

OpenAPI / Swagger ist der Industriestandard für API-Dokumentation. Eine OpenAPI-Spezifikation (YAML oder JSON) beschreibt alle Endpunkte, Parameter, Request- und Response-Schemata sowie Authentifizierungsanforderungen in maschinenlesbarer Form. Swagger UI und ReDoc generieren daraus automatisch interaktive Dokumentation. Wichtig: Die OpenAPI-Spezifikation sollte aus dem Code generiert werden (Code-First), nicht manuell gepflegt werden – manuelle Dokumentation ist immer veraltet.

Rate Limiting schützt die API vor Überlastung durch zu viele Requests. Das Limit wird per Client (API-Key, IP-Adresse) und Zeitfenster definiert: z.B. 1.000 Requests pro Stunde. Der Statuscode 429 Too Many Requests signalisiert dem Client, dass er das Limit überschritten hat. Die Headers X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset informieren den Client über seinen aktuellen Kontingentstand.

Sicherheit bei APIs umfasst mehrere Ebenen. CORS (Cross-Origin Resource Sharing) muss korrekt konfiguriert sein: Nur vertrauenswürdige Origins dürfen die API aus dem Browser aufrufen. Input-Validierung ist Pflicht – alle eingehenden Daten müssen serverseitig validiert werden, nie nur clientseitig. SQL-Injection, XSS und andere Injection-Angriffe sind bei APIs ebenso relevant wie bei Webseiten. Prepared Statements und ORM-Abfragen schützen gegen SQL-Injection. Alle API-Kommunikation muss über HTTPS laufen – unverschlüsselte APIs sind in der Produktion nicht akzeptabel.