Eine öffentliche API entwerfen
Eine API als langlebigen Vertrag entwerfen — versioniert, dokumentiert, stabil für ihre Nutzer.
Was ist das? · Playbook
Ein wiederholbares Vorgehen für eine wiederkehrende Herausforderung — Situation, Schritte, Entscheidungspunkte und Validierung. Wie wir es tun, nicht warum. Zur Übersicht
Wann dieses Playbook greift.
Eine API soll von Partnern, mobilen Apps oder mehreren Frontends genutzt werden. Anders als interner Code ist eine öffentliche Schnittstelle ein Versprechen: Änderungen betreffen fremde Systeme, die man nicht kontrolliert.
Ziele
- Die API bleibt für ihre Nutzer stabil und vorhersehbar.
- Sie kann sich weiterentwickeln, ohne bestehende Integrationen zu brechen.
- Sie ist dokumentiert und ohne Rückfragen nutzbar.
Typische Risiken
- Breaking Changes, die Integrationen stillschweigend brechen.
- Interne Datenmodelle nach außen durchreichen — enge Kopplung.
- Fehlende Idempotenz bei wiederholten Aufrufen.
- Unklare Fehler- und Statussemantik.
Bevor wir bauen.
- Nutzer und ihre echten Anwendungsfälle verstehen — nicht die interne Struktur abbilden.
- Ressourcen und ihre Beziehungen modellieren, unabhängig von der Datenbank.
- Versionierungs- und Deprecation-Strategie festlegen, bevor v1 erscheint.
Wie wir vorgehen.
API-first, als Vertrag
Die Schnittstelle wird zuerst entworfen und dokumentiert (etwa als OpenAPI). Der Vertrag steht vor der Implementierung.
Nach außen entkoppeln
Externe Repräsentationen sind bewusst von internen Modellen getrennt. Interne Änderungen dürfen die API nicht zwingen, sich zu ändern.
Idempotenz und klare Semantik
Schreiboperationen sind idempotent; Statuscodes, Fehlerformate und Pagination sind einheitlich und dokumentiert.
Additiv versionieren
Änderungen sind bevorzugt additiv. Ein Breaking Change bedeutet eine neue Version mit klarer Deprecation-Frist.
Fragen, die eine Antwort brauchen.
Bildet die Ressource den Anwendungsfall der Nutzer ab — oder die interne Tabelle?
Ist jede Schreiboperation idempotent?
Ist die Änderung additiv, oder braucht sie eine neue Version?
Ist das Verhalten dokumentiert, bevor es implementiert wird?
Validierung
- Die Dokumentation reicht aus, um ohne Rückfragen zu integrieren.
- Contract-Tests prüfen den Vertrag gegen die Implementierung.
- Wiederholte Aufrufe erzeugen keinen doppelten Effekt.
Häufige Fehler
- Interne Datenmodelle 1:1 als API exponieren.
- Versionierung erst nachträglich einführen.
- Fehler unspezifisch oder inkonsistent zurückgeben.
- Breaking Changes ohne Deprecation-Frist ausrollen.
Wann wir bewusst anders vorgehen.
- Für rein interne Kommunikation zwischen eigenen Diensten kann eine engere Kopplung akzeptabel sein — dort ist der Vertrag günstiger zu ändern.
- Wo Clients sehr unterschiedliche Datenschnitte brauchen, prüfen wir GraphQL statt strikt ressourcenorientiertem REST.
Beteiligte Phasen der Engineering Method
Setzen Sie Ihren Engineering-Weg fort.
Verwandte Konzepte, Entscheidungen, Playbooks und Standpunkte — als zusammenhängender Pfad, nicht als Linkliste.
Leistungen
Verwandte Konzepte
Engineering-Entscheidungen
Standpunkte
Eine ähnliche Herausforderung?
Playbooks zeigen, wie wir denken. Für Ihr konkretes Vorhaben sprechen Sie mit der Geschäftsführung — technisch, ohne Vertrieb.
