Senior Java · Fachbereich

API Design Studio

Stabile HTTP-, OpenAPI-, gRPC- und GraphQL-Verträge mit Evolutions- und Fehlerstrategie. Nutze die Seite für eine konkrete Engineering-Aufgabe: Kläre zuerst Ziel und Risiko und halte danach Ergebnis, Nachweis und nächsten Schritt fest.

Zur Übersicht

Arbeitsauftrag

Wann verwenden?

Wenn ein HTTP-, Event-, gRPC- oder GraphQL-Vertrag neu entsteht oder kompatibel verändert werden muss.

Nicht dafür verwenden

Nicht für interne Methoden- oder Klassenentwürfe ohne externen Verbraucher.

Definition of Done

Consumer inventarisiert; Fehlervertrag und Kompatibilität geprüft; versionierter Vertrag, Contract-Tests und Rolloutplan liegen vor.

APIs aus fachlichen Fähigkeiten ableiten

Fehler und Idempotenz als Vertragsbestandteil behandeln

Breaking Changes früh erkennen

Entscheidungsmatrix

Stil	Geeignet wenn	Hauptrisiko	Pflichtnachweis
HTTP/REST	direkte Anfrage mit unmittelbarer Antwort	enge zeitliche Kopplung	OpenAPI- und Consumer-Contract-Test
Event	mehrere unabhängige Reaktionen folgen	Duplikate und verzögerte Verarbeitung	Schema-, Idempotenz- und Replay-Test
gRPC	interne, typisierte Kommunikation mit hoher Frequenz	schwerere Browser- und Debug-Integration	Proto-Kompatibilität und Deadline-Test

Alle Kapitel

Ressourcen und Use Cases

Eine REST-Ressource repräsentiert fachlich verständliche Zustände. Nicht jeder interne Service benötigt einen eigenen Endpunkt.

Commands, Abfragen und langlaufende Prozesse dürfen unterschiedliche HTTP-Modelle verwenden, solange Verhalten und Status eindeutig sind.

HTTP

POST /api/orders
Idempotency-Key: 8f8e...

201 Created
Location: /api/orders/ord-4711

{
  "orderId": "ord-4711",
  "status": "ACCEPTED"
}

Fehlervertrag

Fehlerantworten trennen maschinenlesbaren Code, menschenlesbare Erklärung und Diagnosekontext. Interne Stacktraces und sensible Daten verlassen den Service nicht.

JSON

{
  "type": "https://errors.example.com/order/empty",
  "title": "Auftrag enthält keine Positionen",
  "status": 422,
  "code": "ORDER_EMPTY",
  "correlationId": "7b4c..."
}

Evolution

Kompatible Erweiterungen, Deprecation, Parallelbetrieb und Konsumentenkommunikation werden geplant. Ein Versionssprung ist kein Ersatz für eine Migrationsstrategie.

Praxisartefakt · API-Änderungsnotiz

Änderung: deliveryWindow wird optional zu POST /orders ergänzt.
Consumer: Web Checkout, Mobile App und Partner Gateway sind inventarisiert.
Kompatibilität: Fehlendes Feld behält bisheriges Verhalten; unbekannte Felder werden toleriert.
Rollout: Server zuerst, danach Consumer einzeln; Nutzung über Metrik beobachten.
Rollback: Server ignoriert das neue Feld, Vertrag bleibt weiterhin lesbar.