Stellen Sie sich vor, eine Bestellwebsite sendet einen neuen Auftrag an ein operatives System. Dieses speichert ihn, doch die Bestätigung erreicht die Website nicht. Soll die Website es erneut versuchen? Könnte dadurch ein zweiter Auftrag entstehen? Diese beispielhafte Situation zeigt, warum ein API-Vertrag für betriebliche Abläufe wichtig ist. Er beschreibt das erwartete Verhalten auf beiden Seiten – einschließlich der Fälle, die eine erfolgreiche Demonstration womöglich nie zeigt.
Auf dieser Seite
Beginnen Sie beim Geschäftsablauf und der Datenverantwortung
Bilden Sie eine Interaktion von der Nutzeraktion bis zum bestätigten Ergebnis ab. Klären Sie im Bestellbeispiel, wer die Bestellreferenz erzeugt, welches System über die Annahme entscheidet und wo der Kunde den Status prüft. Unterscheiden Sie zwischen einer eingegangenen Anfrage und einer angenommenen Bestellung: Das können verschiedene Ereignisse sein. Legen Sie außerdem fest, welches System welche Information ändern darf. Wenn beide Systeme eine Lieferadresse bearbeiten können, braucht der Vertrag eine Aktualisierungsregel, statt anzunehmen, dass die neueste Bildschirmansicht den maßgeblichen Wert enthält.
- Benennen Sie die Verantwortung für Bestell-, Kunden- und Statusinformationen.
- Legen Sie fest, welches Ergebnis der Nutzer sofort sehen muss.
- Erfassen Sie spätere Aktualisierungen, die das empfangende System senden muss.
Definieren Sie Felder konkret
Dokumentieren Sie für jede Nachricht Pflichtangaben, zulässige Werte und die Bedeutung fehlender Informationen. Ein Preis benötigt eine Währung und eine eindeutige Interpretation; ein Zeitstempel eine vereinbarte Zeitzonenregel. Besprechen Sie diese Regeln anhand einer realistischen Beispielbestellung. Klären Sie, ob „storniert“ die gesamte Bestellung oder einen einzelnen Artikel bezeichnet und ob eine leere Adresse unbekannt oder absichtlich entfernt bedeutet. Beschreiben Sie, welche Datensätze jeder Aufrufer lesen oder ändern darf. Diese Entscheidungen betreffen sowohl die Spezifikation als auch die Nutzung der Anwendung; übereinstimmende Feldnamen allein beantworten sie nicht.
Legen Sie wiederholte Anfragen und hilfreiche Fehlermeldungen fest
Für die Beispielbestellung könnte folgende Regel gelten: Wird innerhalb einer vereinbarten Aufbewahrungsfrist dieselbe Anfragekennung mit identischen Bestelldaten erneut gesendet, kommt die bereits vorhandene Bestellreferenz zurück. Wird diese Kennung mit anderen Daten wiederverwendet, entsteht ein Konflikt, den der Aufrufer klären muss. Definieren Sie den Geltungsbereich der Kennung und die Aufbewahrungsfrist ausdrücklich. Unterscheiden Sie anschließend korrigierbare Eingabefehler von vorübergehenden Störungen. Eine Zeitüberschreitung allein sagt nicht aus, ob die Bestellung gespeichert wurde. Der Aufrufer braucht deshalb eine Möglichkeit, das Ergebnis zu prüfen, bevor er den nächsten Schritt entscheidet.
- Fehlende Lieferadresse: eine Erklärung auf Feldebene zurückgeben; die Anfrage vor erneutem Senden korrigieren.
- Unklares Ergebnis: die Anfragekennung nachschlagen und mit ihrem gespeicherten Zustand abgleichen.
- Vorübergehender Dienstausfall: die vereinbarte Wiederholungsstrategie befolgen; nicht für jeden Versuch eine neue Bestellidentität erzeugen.
Vereinbaren Sie Tests und Änderungen am Vertrag
Lassen Sie beide Teams eine erfolgreiche Bestellung, eine wiederholte Anfrage, eine ungültige Adresse und eine unterbrochene Bestätigung durchgehen. Prüfen Sie, ob sie in jedem Fall dasselbe Ergebnis erwarten. Bewahren Sie diese Beispiele bei der Spezifikation auf und nutzen Sie sie bei Änderungen der Integration. Benennen Sie die Verantwortlichen für die Freigabe von Änderungen, die Information angebundener Teams und die Untersuchung von Störungen. Eine Übergabe sollte erklären, wie der Support eine Anfrage nachvollzieht, ohne unnötige Kundendaten offenzulegen, und wie eine inkompatible Änderung bei bestehenden API-Nutzern eingeführt wird.