Modul 5: API Design — REST, GraphQL, gRPC und Versioning

APIs sind Verträge

Eine API ist ein Vertrag zwischen Konsumenten und Anbieter. Änderungen am Vertrag brechen Konsumenten. Gutes API-Design minimiert Brüche, maximiert Stabilität und macht die API selbsterklärend. Die Wahl des Stils (REST, GraphQL, gRPC) ist weniger wichtig als die Konsistenz.

Lesson 1: REST — Ressourcen und HTTP-Verben

REST modelliert Ressourcen (Nomen, nicht Verben) und nutzt HTTP-Verben: GET (lesen), POST (erstellen), PUT (ersetzen), PATCH (teilen), DELETE (löschen). Zustandscodes sind Teil des Vertrags: 200 OK, 201 Created, 204 No Content, 400 Bad Request, 404 Not Found, 409 Conflict. Hypermedia (HATEOAS) ist optional, aber Links in der Response machen die API navigierbar.

GET    /api/policies/42          -> 200 OK          (Policy lesen)
POST   /api/policies            -> 201 Created      (neu; Location-Header)
PUT    /api/policies/42          -> 200 OK          (vollständig ersetzen)
PATCH  /api/policies/42          -> 200 OK          (teilweise aktualisieren)
DELETE /api/policies/42          -> 204 No Content  (gelöscht, leerer Body)
POST   /api/policies/42/claims   -> 201 Created      (Sub-Ressource anlegen)

Lesson 2: GraphQL — ein Endpoint, viele Formen

GraphQL bietet einen Endpoint, bei dem der Konsument genau die Felder anfordert, die er braucht. Vorteil: Kein Over-Fetching, kein Under-Fetching, eine Abfrage für verschachtelte Daten. Nachteile: Komplexeres Caching (POST, nicht GET), N+1-Gefahr ohne DataLoader, Autorisierung pro Feld statt pro Endpoint.

Lesson 3: gRPC — hochperformant, binär

gRPC nutzt Protocol Buffers (binär, typisiert) und HTTP/2. Vorteil: Schnell, kompakt, Streaming, Code-Generation für viele Sprachen. Nachteile: Nicht browser-tauglich ohne Gateway, binär ist nicht menschenlesbar, Schema-Änderungen erfordern Sorgfalt. Ideal für Service-to-Service-Kommunikation.

Lesson 4: Versioning und Evolution

APIs evolvieren. Versioning-Strategien: URI-Pfad (/api/v2/...), Header (Accept-Version), Query-Parameter (?version=2). URI-Pfad ist explizit und einfach zu debuggen. Brechende Änderungen = neue Major-Version. Nicht-brechende Änderungen (neue Felder, neue Endpoints) brauchen keine neue Version. Faustregel: 2 Jahre Kompatibilität, dann Deprecation.

Lesson 5: Pagination, Filtering, Error Handling

Paginierung: cursor-based (stabil bei Einfügungen) statt offset-based (verschiebt sich). Filtering: Query-Parameter mit klarer Semantik (?status=active&cropType=wheat). Fehler: Konsistentes Format (RFC 7807 ProblemDetail), Maschinen-lesbar (error code, field, message), nie Stacktraces. Idempotenz bei POST über Idempotency-Key.