API-Verträge
Ein API-Vertrag legt Daten, Bedeutung und beobachtbares Verhalten einer Schnittstelle fest. Er umfasst Erfolg und relevante Fehlerfälle.
- EingabeWas der Aufrufer liefern muss.
- ErgebnisseErfolg und Fehler unterscheidbar.
- EigentümerEin Baustein verantwortet den Vertrag.
Einordnung
Warum das wichtig ist
Ohne klaren Vertrag raten Aufrufer, was ein Aufruf bedeutet und wie Fehler aussehen. Dann bricht Zusammenarbeit an Randfällen. Wie Verträge sich später ändern, behandelt API-Versionierung.
Dieser Baustein erklärt den Inhalt eines Schnittstellenvertrags. Für Änderungen an bestehenden Verträgen siehe API-Versionierung.
Auf einen Blick · Vertrag zwischen Aufrufer und Anbieter
Ausgefüllter Vertrag Bestand reservieren
Bestellung reserviert über den Vertrag des Lagermoduls zwei Tassen für B-1042. Die Reservierung besitzt eine stabile Kennung und ein Ablaufdatum.
So liest du das Bild
- Eingabe Abschnitt Eingabe: Bestell-ID B-1042, Produkt T-7, Menge 2.
- Ergebnisse Abschnitte Erfolg (Reservierungs-ID R-77) und Fachlicher Fehler (BESTAND_REICHT_NICHT).
- Eigentümer Abschnitt Eigentümer: Lagermodul; Abschnitt Wiederholung zur selben Bestell-ID und Position.
- Operation
- Bestand reservieren
- Eingabe
- Bestell-ID B-1042, Produkt T-7, Menge 2
- Erfolg
- Reservierungs-ID R-77, gültig bis 10:15
- Fachlicher Fehler
- BESTAND_REICHT_NICHT mit verfügbarer Menge
- Wiederholung
- Dieselbe Bestell-ID und Position bezeichnen denselben Reservierungsauftrag
- Eigentümer
- Lagermodul
Nutzen & Grenzen
Hilft, wenn
- Ein gemeinsamer beobachtbarer Vertrag unterstützt unabhängige Entwicklung von Anbietern und Konsumenten.
- Verbindliche Bedeutung, Fehlerformen und Zeitverhalten geben dem Vertrag mehr Aussagekraft als ein Feldschema allein.
- Prüfbare Zusagen erleichtern kompatible Änderungen, während eine Schnittstelle über mehrere Releases wächst.
Grenzen
- Ein Schema allein legt Bedeutung und Fehlerverhalten nicht fest; ohne Zusagen zu beidem interpretieren Aufrufer unterschiedlich.
- Stille Bedeutungsänderungen brechen Aufrufer trotz unverändertem Datentyp und zählen wie inkompatible Änderungen; siehe API-Versionierung.
- Der Vertrag bleibt nur belastbar, solange Konsumenten ihn prüfen; ungeprüfte Zusagen sind Annahmen.
In der Praxis
- Beschreibe Operation, Datenbedeutung, Fehler, Identität und Zeitverhalten aus Sicht eines Konsumenten. Vermeide Verträge, die nur interne Feldnamen dokumentieren.
- Prüfe Vertragstests gegen Produzent und Verbraucher und erfasse Kompatibilität bei Änderungen. HTTP-Methoden und Statuscodes behalten dabei ihre protokollgemäße Semantik.
- Grenze Ressourcendarstellung, HTTP-Protokoll und fachlichen Vertrag voneinander ab. API-Versionierung steuert Migration; Authentifizierung & Autorisierung regelt Zugriff.
- Semantische Kompatibilität an Beispielen prüfen. Vereinbart für einen rabattierten Warenkorb Betrag, Währung und Steuerbehandlung. Nutzt dieses Beispiel in Vertragstests, damit auch bei unverändertem Feldnamen eine geänderte fachliche Bedeutung auffällt.
Ausführliche Erklärung lesen
Ein API-Vertrag beschreibt erlaubte Operationen, Datenbedeutung, Fehlerformen und beobachtbares Verhalten. HTTP ist ein Protokoll mit festgelegter Semantik für Methoden, Statuscodes und Header. REST ist ein Architekturstil mit zusätzlichen Einschränkungen wie einheitlicher Schnittstelle und Zustandslosigkeit. Eine HTTP-API entspricht REST, wenn sie diese Constraints erfüllt.
Anbieter und Konsumenten entwickeln den Vertrag gemeinsam weiter, ohne interne Umsetzung offenzulegen. Schema und Kompatibilitätsprüfungen machen Form und Verhalten prüfbar. Änderungen an der Bedeutung können inkompatibel sein, auch wenn Feldnamen und Datentypen gleich bleiben.
API-Versionierung behandelt Kompatibilität über mehrere Vertragsstände; Authentifizierung & Autorisierung regelt Identität und Zugriffsrecht als eigene Sicherheitszusage.
OpenAPI beschreibt synchrone HTTP-Schnittstellen, AsyncAPI beschreibt Nachrichtenverträge. Mit Consumer-Driven Contracts (etwa mit Pact) formulieren Nutzer ihre Erwartungen als Tests, die der Anbieter prüft.
Im Shop braucht ein Betrag neben Zahlenformat und Währung eine eindeutige Bedeutung: netto oder brutto, vor oder nach Rabatt. Anbieter und Konsumenten können dasselbe Schema erfolgreich validieren und trotzdem unterschiedliche Rechnungen erzeugen. Ein fachliches Vertragsbeispiel macht die erwartete Interpretation überprüfbar.
Selbst prüfen
Teste dich in drei Stufen
AblesenIm Bild nachsehen
Welche Kennung liefert das Lager im Erfolgsfall zurück, und wie lange gilt sie?
Lösung mit Begründung ansehen
Die Reservierungs-ID R-77, gültig bis 10:15. Sie bezeichnet die konkrete bestätigte Reservierung.
AnwendenAuf eine neue Lage übertragen
Das Lager liefert BESTAND_REICHT_NICHT mit verfügbarer Menge. Was kann Bestellung damit tun?
Lösung mit Begründung ansehen
Sie kann den Fehlerfall behandeln, zum Beispiel die Menge anpassen oder ablehnen, weil der Vertrag die verfügbare Menge mitliefert.
BewertenEine Alternative abwägen
Soll der Vertrag nur Erfolg beschreiben und Fehler offenlassen? Wie wägst du ab?
Lösung mit Begründung ansehen
Er wird kürzer, aber Bestellung muss unklare Ausgänge raten. Ein Vertrag mit beschriebenem Fehler wie BESTAND_REICHT_NICHT macht jeden Ausgang behandelbar.
Vertiefen
Diese Bausteine führen die Gedanken dieser Seite weiter.
Quellen
- OpenAPI Initiative · Specification (öffnet in neuem Tab)Definiert die maschinenlesbare Beschreibung von HTTP-API-Verträgen.
- AsyncAPI Initiative · Specification (öffnet in neuem Tab)Beschreibt Nachrichten, Kanäle und Verträge ereignisbasierter Schnittstellen.
- Microsoft · Web API Design (öffnet in neuem Tab)Behandelt Ressourcen, HTTP-Verhalten und Versionierungsentscheidungen.
- Gregor Hohpe · The Many Facets of Coupling (öffnet in neuem Tab)Unterscheidet mehrere Dimensionen der Kopplung, darunter zeitliche und semantische Abhängigkeiten.