Eine erfolgreiche Antwort ist noch kein erfolgreicher Prozess
Eine API kann technisch mit Status 200 antworten und fachlich trotzdem das falsche Ergebnis erzeugen. Vielleicht wurde ein Preis im falschen Währungsformat übertragen, eine Bestellung doppelt angelegt oder ein Teil der Positionen verworfen. Umgekehrt kann ein Timeout auftreten, obwohl das Zielsystem die Anfrage bereits verarbeitet hat.
Robustheit entsteht deshalb nicht allein im Controller eines Endpunkts. Sie umfasst Datenvertrag, Authentifizierung, Validierung, Zustandsmodell, Wiederholungen, Idempotenz, Logging, Monitoring und einen manuellen Korrekturweg. Jede dieser Ebenen beantwortet eine andere Fehlerklasse.
Der wichtigste Perspektivwechsel lautet: Eine Schnittstelle ist ein dauerhaft betriebener Geschäftsprozess. Entwicklung und Betrieb können nicht getrennt geplant werden.
Datenhoheit und Vertrag vor dem ersten Request
Bevor Felder zugeordnet werden, muss feststehen, welches System für welche Information führend ist. Darf der Shop einen Produktnamen verändern, wenn das PIM ihn beim nächsten Lauf überschreibt? Entsteht der finale Zahlungsstatus beim Anbieter oder im ERP? Wer vergibt eine Kundennummer?
Ein Datenvertrag beschreibt Objekte, Pflichtfelder, Formate, Einheiten, Kennungen, zulässige Status, Mengen, Aktualität und Versionierung. Er enthält auch fachliche Regeln: Darf ein unbekannter Artikel eine Bestellung blockieren? Wird ein negativer Bestand akzeptiert? Wie werden Stornos abgebildet?
Ohne diese Entscheidungen verlagert sich die Fachlogik in zufällige Mapping-Codes. Spätere Fehler wirken technisch, obwohl die Ursache eine ungeklärte Verantwortung ist.
Fragen für den Datenvertrag
- Welches System ist je Feld führend?
- Welche Kennung bleibt über beide Systeme stabil?
- Welche Felder sind fachlich und technisch verpflichtend?
- Welche Zeitzone, Währung und Einheit gilt?
- Wie werden Löschen, Storno und Korrektur ausgedrückt?
- Welche Daten dürfen protokolliert werden?
- Wie wird eine Vertragsänderung versioniert?
Validierung: syntaktisch korrekt reicht nicht
Syntaktische Validierung prüft, ob ein Feld vorhanden ist und dem erwarteten Typ entspricht. Fachliche Validierung fragt weiter: Ist der Statuswechsel zulässig? Gehört die Adresse zum erlaubten Liefergebiet? Sind Summe und Positionen plausibel? Existiert die referenzierte Kundennummer?
Fehler sollten so früh wie möglich erkannt werden, aber in einer Sprache, die eine Korrektur erlaubt. „Bad Request“ hilft dem Fachbereich kaum. Ein guter Fehlerstatus benennt Datensatz, Regel und betroffenen Wert, ohne sensible Daten unnötig zu wiederholen.
Bei Batchverarbeitung muss entschieden werden, ob ein einzelner Fehler den gesamten Lauf stoppt. Häufig ist eine Teilverarbeitung sinnvoll: valide Datensätze werden übernommen, fehlerhafte erhalten einen Status. Bei voneinander abhängigen Datensätzen kann dagegen ein gemeinsamer Abbruch korrekter sein.
Wiederholungen: nur bei vorübergehenden Fehlern
Netzwerkunterbrechungen, Rate Limits und kurzzeitige Ausfälle gehören zum Betrieb verteilter Systeme. Wiederholungen sind deshalb nötig, dürfen aber nicht jede Fehlerart gleich behandeln. Ein Timeout oder Status 503 kann später erfolgreich sein. Ein ungültiges Pflichtfeld wird durch zehn weitere Versuche nicht richtiger.
Zwischen Versuchen sollte der Abstand wachsen und eine zufällige Streuung enthalten, damit viele Worker nicht gleichzeitig erneut anfragen. Anzahl und Gesamtdauer bleiben begrenzt. Danach wechselt der Vorgang in einen sichtbaren Fehlerstatus oder eine Dead-Letter-Verarbeitung.
Die Wiederholung benötigt außerdem Kontext: Welche Version der Daten wird erneut gesendet? Wurde der Vorgang zwischenzeitlich manuell korrigiert? Ist die ursprüngliche Anforderung noch gültig? Eine Queue speichert nicht nur Payload, sondern auch Zustand und fachliche Identität.
Idempotenz: derselbe Auftrag darf nicht doppelt wirken
Stellen Sie sich vor, eine Bestellanfrage erreicht das Zielsystem und wird gespeichert. Die Antwort geht im Netzwerk verloren. Der Sender nimmt einen Fehler an und wiederholt. Ohne Schutz entsteht eine zweite Bestellung, obwohl technisch alles „korrekt“ aussah.
Idempotente Verarbeitung sorgt dafür, dass dieselbe fachliche Operation mehrfach angefragt werden kann, aber nur einmal wirkt. Dazu dienen stabile externe IDs, Idempotenzschlüssel und eine atomare Prüfung beziehungsweise Speicherung. Das Zielsystem gibt bei einer Wiederholung das bereits bekannte Ergebnis zurück.
Nicht jede Operation ist von Natur aus idempotent. „Setze Bestand auf 8“ lässt sich leichter wiederholen als „reduziere Bestand um 2“. Wenn nur die zweite Form möglich ist, braucht es eine eindeutige Bewegungs-ID und ein Buchungsprotokoll.
Teilerfolge und Konsistenz über Systemgrenzen
Innerhalb einer Datenbank kann eine Transaktion mehrere Änderungen gemeinsam bestätigen oder zurückrollen. Über Shop, Payment, ERP und Versand hinweg existiert diese gemeinsame Transaktion meist nicht. Ein Prozess kann nach der Zahlung, aber vor der ERP-Buchung abbrechen.
Dafür braucht es ein Zustandsmodell. Jeder Schritt wird mit fachlicher Kennung und Ergebnis protokolliert. Der nächste Schritt beginnt nur, wenn seine Voraussetzung erfüllt ist. Bei einem Fehler wird entweder wiederholt, ein kompensierender Schritt ausgeführt oder eine manuelle Prüfung angelegt.
Sogenannte Eventual Consistency ist kein Freibrief für beliebige Verzögerung. Fachbereich und Kunden müssen wissen, welche Übergangszeit akzeptabel ist und wie ein hängen gebliebener Vorgang erkannt wird. Für manche Prozesse zählt Sekundengenauigkeit, für andere genügt ein nächtlicher Abgleich.
Logging mit Korrelation statt Datenfriedhof
Logs sollen eine konkrete Frage beantworten: Was geschah mit Bestellung X oder Importlauf Y? Dafür benötigt jeder Vorgang eine Korrelations-ID, die über beteiligte Schritte weitergegeben wird. Zeit, System, Operation, Ergebnis, Dauer und Fehlerklasse bilden den Kern.
Vollständige Payloads in Logs sind oft riskant. Sie können personenbezogene Daten, Tokens oder Geschäftsgeheimnisse enthalten und die Suche erschweren. Besser sind gezielt ausgewählte Identifikatoren und strukturierte Felder. Sensible Werte werden maskiert oder gar nicht protokolliert.
Ein Log ohne Aufbewahrungskonzept und Zugriffsschutz ist kein fertiges Betriebsinstrument. Es muss feststehen, wer es einsehen darf, wie lange Daten benötigt werden und welche Alarmregeln daraus entstehen.
Nützliche strukturierte Felder
- Korrelations- und fachliche Vorgangs-ID
- Quell- und Zielsystem
- Operation und Vertragsversion
- Versuchsnummer und Zeitstempel
- Ergebnis- und Fehlerklasse
- Verarbeitungsdauer und Anzahl Datensätze
- Verweis auf manuellen Prüfstatus
Monitoring: technische und fachliche Signale verbinden
Technisches Monitoring erkennt Antwortzeiten, Fehlerquoten, Queue-Länge und Ressourcenauslastung. Fachliches Monitoring erkennt, dass seit zwei Stunden keine Bestellung übertragen wurde, obwohl normalerweise laufend Bestellungen eintreffen, oder dass auffällig viele Produkte ohne Kategorie bleiben.
Beide Ebenen sind nötig. Eine API kann technisch gesund sein, während keine Daten mehr gesendet werden. Umgekehrt kann eine steigende Queue vorübergehend akzeptabel sein, wenn ein geplanter Import läuft. Alarmgrenzen benötigen Kontext und eine verantwortliche Person, sonst werden Warnungen ignoriert.
Ein manueller Korrekturweg gehört zur Automatisierung
Vollautomatisierung ohne Ausnahmebehandlung ist in vielen Geschäftsprozessen unrealistisch. Ein Datensatz kann fachlich unvollständig sein, ein externer Dienst kann neue Regeln einführen oder eine Zuordnung kann menschliche Entscheidung brauchen.
Ein guter Korrekturweg zeigt den Fehler verständlich, erlaubt eine berechtigte Änderung oder Genehmigung und startet danach gezielt erneut. Er verhindert direkte Datenbankeingriffe ohne Protokoll. Rollen und Berechtigungen sind dabei ebenso wichtig wie die technische Funktion.
Die Anzahl manueller Fälle ist außerdem ein Verbesserungssignal. Häufen sich dieselben Ursachen, sollte die Validierung, Datenquelle oder fachliche Regel angepasst werden.
Teststrategie für Schnittstellen
Happy-Path-Tests beweisen nur, dass ein idealer Datensatz verarbeitet werden kann. Robuste Tests enthalten fehlende Felder, ungültige Statuswechsel, doppelte Nachrichten, Timeouts, Rate Limits, Teilerfolge, große Mengen, Sonderzeichen und eine Wiederaufnahme nach Fehlern.
Vertragstests prüfen, ob Sender und Empfänger dieselbe Struktur verstehen. Integrationstests prüfen reale Komponenten in einer kontrollierten Umgebung. End-to-End-Tests decken den geschäftlichen Gesamtpfad ab, sind aber langsamer und störanfälliger. Eine sinnvolle Mischung schützt kritische Regeln, ohne jede Prüfung vom externen Dienst abhängig zu machen.
Die Betriebscheckliste vor dem Go-live
Vor der Inbetriebnahme sollten Authentifizierung, Geheimnisrotation, Limits, Timeouts, Wiederholungen, Idempotenz, Logging, Alarmierung, Datenschutz, Verantwortlichkeiten und Rückfallweg geklärt sein. Ebenso wichtig ist die Frage, wie alte oder während des Ausfalls entstandene Daten nachgezogen werden.
Nach dem Go-live folgt eine Phase erhöhter Beobachtung. Kontrollwerte aus Quell- und Zielsystem werden verglichen. Fehlerklassen und Laufzeiten zeigen, ob Annahmen aus Testdaten im realen Betrieb gelten. Erst dann wird die Schnittstelle zur normalen Betriebsroutine.