REST-API-Design — Praktische Lektionen aus realen Projekten

In den letzten zwei Jahren haben wir mehr als ein Dutzend REST-APIs für verschiedene Kunden entworfen. Einige sind gut gelungen, andere weniger. Hier ist eine Zusammenfassung dessen, was funktioniert, was nicht, und was wir anders machen würden.

URL-Design — Konsistenz vor Cleverness¶

Substantive, keine Verben. /api/v1/users, nicht /api/v1/getUsers. Konsequent Plural. Verschachtelung nur eine Ebene tief — /users/123/orders ist in Ordnung, tiefer nicht. Bevorzugen Sie /order-items/789 mit Filterung.

Versionierung — URL-Pfad hat gewonnen¶

Wir haben drei Ansätze ausprobiert: URL-Pfad (/api/v1/), Header (Accept: application/vnd.myapp.v1+json) und Query-Parameter. URL-Pfad hat gewonnen — jeder Entwickler versteht ihn, er funktioniert im Browser, und Caches verstehen ihn auch.

Error Handling — Seien Sie ausführlich¶

Unsere erste API gab zurück: {"error": "Bad request"}. Nutzlos. Unser aktuelles Format (inspiriert von RFC 7807):

{
  "status": 422,
  "code": "VALIDATION_ERROR",
  "message": "Validation failed",
  "details": [
    {"field": "email", "message": "Invalid email address format"}
  ],
  "traceId": "abc-123-def"
}

HATEOAS — Theorie vs. Praxis¶

Wir haben Spring HATEOAS ausprobiert. Für öffentliche APIs ergibt es Sinn. Für interne APIs, bei denen das Frontend-Team nebenan sitzt? Overhead ohne Nutzen. Frontend-Entwickler haben die Links ignoriert und URLs trotzdem hartcodiert. In der Theorie schön, in der Praxis anders.

Dokumentation — Swagger ist Pflicht¶

Swagger generiert interaktive Dokumentation aus Annotationen. Ein Game-Changer für das Onboarding. Aber Contract-First ist besser — YAML manuell schreiben und Code daraus generieren. Mehr Arbeit, aber eine Single Source of Truth.

Sicherheit — OAuth 2.0 und JWT¶

OAuth 2.0 mit JWT-Tokens. Access Token im Authorization-Header, Refresh Token in einem httpOnly-Cookie. JWT ist self-contained — die Verifizierung erfordert keinen Aufruf an den Auth-Server. Aber JWT kann nicht widerrufen werden — wir lösen das mit einer Blacklist in Redis.

Top-5-Fehler, die wir gemacht haben¶

1. 200 OK für Fehler zurückgeben (mit dem Fehler im Body)
2. Kein Rate Limiting — DoS vom eigenen Frontend
3. PUT statt PATCH für partielle Updates verwenden
4. Kein Request/Response-Logging
5. Übermäßiger Optimismus bezüglich Rückwärtskompatibilität

Eine API ist ein Produkt¶

Eine REST-API ist nicht nur ein technisches Detail — sie ist eine Schnittstelle für Menschen (Entwickler). Entwerfen Sie sie mit Empathie. Dokumentieren Sie sie. Versionieren Sie sie. Und vor allem — testen Sie sie aus der Perspektive des Konsumenten.