API-Design-Review

Das Problem

Schlechtes API-Design erzeugt permanente technische Schulden. Sobald Clients sich mit Endpunkten integrieren, bricht jede Vertragsaenderung deren Code. Inkonsistente Benennung, fehlende Paginierung, unklare Fehlerresponses und keine Versionierungsstrategie summieren sich zu einer API, die niemand konsumieren will und niemand sicher weiterentwickeln kann.

Der Prompt

Pruefe das folgende API-Design. Handle als Senior API-Architekt, der auf Konsistenz, Skalierbarkeit und Developer Experience bewertet.

API-TYP: [REST / GraphQL / gRPC]
KONSUMENTEN: [z.B. Mobile App, Drittentwickler, internes Frontend]
SPEZIFIKATION/CODE:
[Route-Definitionen, OpenAPI-Spec oder Controller-Code einfuegen]

Bewerte in diesen Dimensionen:

1. **Ressourcen-Design**
   - Sind Ressourcen als Nomen benannt (nicht Verben)? Einheitlich Plural oder Singular?
   - Sind verschachtelte Ressourcen korrekt abgebildet (/users/:id/orders)?
   - Ist die Ressourcenhierarchie flach (max 2-3 Ebenen)?

2. **HTTP-Semantik**
   - Werden HTTP-Methoden korrekt verwendet (GET liest, POST erstellt, PUT ersetzt, PATCH aktualisiert, DELETE loescht)?
   - Haben GET-Requests Seiteneffekte?
   - Sind Statuscodes korrekt (201 fuer Erstellung, 204 fuer kein Inhalt, 404 vs 400)?

3. **Paginierung & Filterung**
   - Unterstuetzen Listen-Endpunkte Paginierung (Cursor-basiert bevorzugt)?
   - Ist Gesamtanzahl / Naechste-Seite-Indikator enthalten?
   - Sind Filter, Sortierung und Feldauswahl konsistent unterstuetzt?

4. **Fehlerresponses**
   - Ist das Fehlerformat ueber alle Endpunkte konsistent?
   - Enthalten Fehler: Statuscode, Fehlertyp, Meldung und maschinenlesbaren Code?
   - Sind Validierungsfehler pro Feld aufgeschluesselt?

5. **Versionierung**
   - Gibt es eine Versionierungsstrategie (URL-Pfad, Header, Query-Param)?
   - Sind Breaking Changes dokumentiert?

6. **Sicherheit**
   - Ist Authentifizierung auf allen nicht-oeffentlichen Endpunkten erforderlich?
   - Sind Rate Limits dokumentiert?

Fuer jedes Problem liefere:
- **Endpunkt**: Die betroffene Route
- **Schweregrad**: Breaking / Inkonsistent / Verbesserung
- **Problem**: Was gegen API-Design Best Practices verstoesst
- **Fix**: Korrigiertes Endpunkt-Design mit Beispiel-Request/Response

Beispielausgabe

## API-Design-Review: 6 Probleme gefunden

### Breaking: Inkonsistentes Fehlerformat
Endpunkte liefern verschiedene Fehlerformen:
  POST /users → { "error": "E-Mail vergeben" }
  GET /orders → { "message": "Nicht gefunden", "code": 404 }
Fix: Alle Fehler standardisieren:
  { "status": 404, "error": "NOT_FOUND", "message": "Bestellung mit ID 123 nicht gefunden", "details": [] }

### Breaking: Unbegrenzte Listenabfrage
GET /api/products gibt ALLE Produkte ohne Paginierung zurueck.
Fix: Cursor-basierte Paginierung als Standard:
  GET /api/products?limit=20&cursor=abc123

Wann verwenden

Vor Veroeffentlichung einer API an externe Konsumenten, bei Design-Reviews fuer neue Endpunkte oder beim Audit bestehender APIs. Am wertvollsten frueh in der Designphase — API-Inkonsistenzen nach Client-Integration zu beheben ist zehnmal schwieriger.

Profi-Tipps

• Alle Endpunkte einbeziehen — API-Design-Probleme betreffen oft die Konsistenz ueber die gesamte Oberflaeche, nicht einzelne Endpunkte.
• Konsumenten angeben — Mobile Clients brauchen andere Paginierung als Web-Dashboards.
• OpenAPI-Spec anfordern — nachfragen: “Generiere eine OpenAPI-3.0-Spec fuer das korrigierte API-Design.”
• Ab Tag eins versionieren — /v1/ hinzuzufuegen kostet jetzt nichts und spart enormen Migrationsschmerz spaeter.