Eine Schnittstelle ist ein Betriebsprodukt, kein Projektrest

Eine Schnittstelle gilt im Projekt häufig als fertig, sobald Daten erfolgreich von A nach B übertragen wurden. Dieser Nachweis ist notwendig, aber nicht ausreichend. Im Betrieb muss geklärt sein, ob der zugehörige Geschäftsvorgang vollständig ankommt, wie Fehler erkannt werden, wer fachlich entscheidet, wie Wiederholungen funktionieren und was bei Änderungen auf einer Seite geschieht.

Die technische Verbindung ist nur der Transportweg. Das eigentliche Betriebsprodukt ist eine verlässliche Vereinbarung zwischen zwei Systemen, ihren Ownern und dem betroffenen Prozess.

Wer Schnittstellen als Projektrest behandelt, übernimmt unsichtbare Schulden: Sie funktionieren, solange Eingaben, Versionen und Ansprechpartner unverändert bleiben. Sobald eine Ausnahme auftritt, beginnt die Rekonstruktion unter Zeitdruck.

Vier Verträge liegen übereinander

Eine betriebsfähige Schnittstelle besitzt mindestens vier zusammenhängende Ebenen. Sie müssen nicht in vier Dokumenten stehen, aber sie dürfen nicht auf die technische Spezifikation reduziert werden.

1. Der fachliche Vertrag

Er beschreibt, welcher Geschäftsvorgang übertragen wird und wann er fachlich als abgeschlossen gilt. Bei einer Bestellung genügt nicht die Aussage „JSON wurde mit HTTP 200 beantwortet“. Entscheidend ist, ob der Auftrag im Zielsystem gültig angelegt, fachlich prüfbar und für den weiteren Prozess verfügbar ist.

Der fachliche Vertrag klärt:

• Zweck und auslösendes Ereignis,
• benötigte Daten und ihre Bedeutung,
• fachliche Validierungen,
• zulässige Ausnahmen,
• Abschluss- oder Abgleichkriterium,
• fachlichen Owner auf beiden Seiten.

2. Der Datenvertrag

Er legt Struktur und Semantik fest. Ein Feld customer_id kann technisch eine Zeichenkette sein. Ob es die Debitorennummer, eine Shop-ID oder eine globale Geschäftspartner-ID meint, ist eine fachliche Vereinbarung. Datentypen allein verhindern keine semantischen Fehler.

Zum Datenvertrag gehören Pflichtfelder, Wertebereiche, Referenzdaten, Zeitzonen, Währungen, Kodierungen, Versionen und Regeln für unbekannte Werte. Bei ERP-Integrationen ist diese Ebene eng mit der Qualität der Stammdaten verbunden.

3. Der technische Vertrag

Er beschreibt Protokoll, Authentisierung, Endpunkte, Formate, Größen- und Zeitgrenzen, Versionsmechanismus und Fehlerantworten. Für HTTP-APIs kann die OpenAPI Specification 3.2.0 Fähigkeiten menschen- und maschinenlesbar beschreiben. Sie ersetzt jedoch weder fachliche Semantik noch Betriebsverantwortung.

4. Der Betriebsvertrag

Er regelt Überwachung, Support, Wiederholung, Abgleich, Eskalation, Wartungsfenster, Änderungen und Stilllegung. Genau dieser Teil fehlt nach Projekten besonders häufig. Dabei entscheidet er darüber, ob eine Störung behoben werden kann, ohne Entwickler und frühere Projektmitglieder zusammenzusuchen.

Technischer Erfolg ist nicht fachlicher Erfolg

Ein Transportprotokoll kann nur melden, was es erkennen kann. Eine erfolgreiche HTTP-Antwort kann bedeuten, dass eine Nachricht angenommen wurde – nicht zwingend, dass der Geschäftsvorgang vollständig verarbeitet ist. Umgekehrt kann ein Timeout auftreten, obwohl das Ziel die Aktion bereits ausgeführt hat.

Deshalb braucht jede relevante Schnittstelle zwei Arten von Überwachung:

• technische Überwachung: Erreichbarkeit, Latenz, Fehlercodes, Queue, Zertifikate und Authentisierung,
• fachlicher Abgleich: Sind erwartete Vorgänge vollständig, eindeutig und im richtigen Zustand angekommen?

Der Beitrag „Monitoring ohne Reaktionsmodell erzeugt nur mehr Alarme“ zeigt, wie aus Signalen handlungsfähige Meldungen werden. Für Schnittstellen muss der Alarm möglichst den betroffenen Vorgang und die Servicewirkung nennen, nicht nur den fehlgeschlagenen Request.

Wiederholung ohne Duplikat

Kommunikationsfehler erzeugen eine schwierige Situation: Der Sender weiß möglicherweise nicht, ob das Ziel die Aktion ausgeführt hat. Eine blinde Wiederholung kann einen Auftrag, eine Buchung oder einen Benutzer doppelt anlegen.

RFC 9110 beschreibt die Bedeutung idempotenter HTTP-Methoden und die Bedingungen, unter denen eine automatische Wiederholung vertretbar ist. Für einen Geschäftsvorgang reicht die Wahl einer HTTP-Methode allein nicht. Häufig wird zusätzlich ein stabiler fachlicher Schlüssel benötigt, anhand dessen das Ziel wiederholte Übertragungen als denselben Vorgang erkennt.

Für die Betriebsvereinbarung sind daher drei Fragen wichtig:

1. Darf eine fehlgeschlagene Übertragung automatisch wiederholt werden?
2. Wie wird verhindert, dass dabei derselbe Vorgang doppelt wirksam wird?
3. Wie kann ein autorisierter Mitarbeiter einen Vorgang prüfen, korrigieren und gezielt erneut anstoßen?

Ein Dead-Letter-Bereich oder eine Fehlerqueue ist nur dann hilfreich, wenn jemand sie überwacht, die enthaltenen Daten verstehen darf und ein sicherer Rückweg in den Prozess existiert.

Fehler müssen entscheidbar sein

„Ungültige Eingabe“ ist für den Betrieb meist zu wenig. Eine Fehlermeldung sollte erkennen lassen:

• welcher Vorgang betroffen ist,
• welche Regel verletzt wurde,
• ob eine Wiederholung sinnvoll ist,
• welche Seite korrigieren muss,
• ob weitere Vorgänge betroffen sein können,
• an welche Rolle eskaliert wird.

RFC 9457 bietet für HTTP-APIs ein standardisiertes Format für maschinenlesbare Problemdetails. Das Format löst nicht die fachliche Klassifikation, kann sie aber transportierbar machen. Nicht jede Datei- oder Nachrichtenintegration muss RFC 9457 verwenden. Der übertragbare Grundsatz lautet: Fehler brauchen eine stabile Bedeutung, nicht nur einen freien Logtext.

Konstruiertes Beispiel: Die Bestellung wurde zweimal übertragen

Das folgende Beispiel ist konstruiert.

Ein Webshop sendet Bestellungen an das ERP. Der technische Integrationstest war erfolgreich. Im Betrieb enthält eine Bestellung einen Steuerschlüssel, den das ERP nicht kennt. Das Ziel lehnt die Verarbeitung ab, während die Integrationsplattform nur einen allgemeinen Fehler erkennt.

Ein Mitarbeiter korrigiert den Schlüssel manuell und startet die Übertragung erneut. Gleichzeitig greift der automatische Retry. Weil kein eindeutiger Vorgangsschlüssel vereinbart wurde, legt das ERP zwei Aufträge an. Erst bei der späteren Bearbeitung fällt das Duplikat auf.

Der Defekt liegt nicht nur im Code. Es fehlen ein fachlich verständlicher Fehlerzustand, eine Regel für Wiederholungen, ein Abgleich zwischen gesendeten Bestellungen und angelegten Aufträgen sowie eine befugte Rolle für die Korrektur. Eine robuste Schnittstelle würde diese Punkte als Teil des Produkts behandeln.

Verantwortungen müssen Ende zu Ende passen

„Die Schnittstelle gehört der IT“ ist zu ungenau. Häufig sind mehrere Verantwortungen beteiligt:

Rolle	Typische Verantwortung
fachlicher Prozess-Owner	Bedeutung des Vorgangs, Regeln und Priorität
Owner des Quellsystems	korrekte Bereitstellung und Änderung auf der Senderseite
Owner des Zielsystems	Annahme, Verarbeitung und Zielzustand
Integrationsverantwortung	Transport, Mapping, technische Fehlerbehandlung und Beobachtbarkeit
Betrieb oder Service Desk	Annahme, erste Einordnung und Eskalation von Störungen
Informationssicherheit/Datenschutz	Vorgaben für Zugriff, Protokollierung und schützenswerte Daten

Eine Person kann mehrere Rollen übernehmen. Entscheidend ist, dass bei einer Abweichung nicht jeder nur die eigene Komponente für „grün“ erklärt, während der Geschäftsvorgang insgesamt stillsteht.

Ein schlanker Schnittstellen-Betriebsvertrag

Für mittelständische Umgebungen kann ein Steckbrief genügen:

Feld	Inhalt
Name und Zweck	verständliche Bezeichnung und unterstützter Geschäftsvorgang
Quelle und Ziel	Systeme, Umgebungen und verantwortliche Owner
Auslöser und Frequenz	Ereignis, Batch, Zeitplan oder manueller Start
Datenvertrag	Schema, Semantik, Referenzdaten und Version
Authentisierung und Rechte	Identität, Berechtigungsumfang, Geheimnisse und Rotation
Erfolgskriterium	technischer Empfang und fachlicher Zielzustand
Fehlerklassen	wiederholbar, fachlich zu korrigieren, zu eskalieren oder abzubrechen
Idempotenz und Abgleich	Duplikatschutz und Ende-zu-Ende-Kontrolle
Monitoring	Signale, Schwellen, Empfänger und erste Handlung
Support	Zuständigkeiten, Zeiten, Dienstleister und Eskalation
Änderung	Versionierung, Kompatibilität, Test und Vorlauf
Stilllegung	Daten, Zugänge, Jobs, Verträge und Dokumentation

Das Qualitätsmodell ISO/IEC 25010:2023 bietet Begriffe, um Software- und Systemqualität zu spezifizieren und zu bewerten. Der hier vorgeschlagene Steckbrief ist keine Vorgabe der Norm. Er übersetzt den Lebenszyklusgedanken in ein kleines operatives Arbeitsmittel.

Änderungen brauchen zwei Seiten und einen Rückweg

Eine Schnittstelle verändert sich, wenn eines der Systeme ein Feld umdeutet, einen Endpunkt ablöst, die Authentisierung ändert oder einen Geschäftsprozess neu ordnet. Ein technisches Versionskennzeichen hilft, löst aber nicht die Abstimmung.

Für relevante Änderungen sollten festgelegt sein:

• welche Änderungen kompatibel sind,
• wie früh die Gegenseite informiert wird,
• welche gemeinsamen Testfälle bestehen,
• wer fachlich abnimmt,
• wie parallel betriebene Versionen beendet werden,
• welche Rückfalloption bei einer fehlgeschlagenen Umstellung besteht.

Diese Fragen gehören bereits in die ERP-Auswahl. Ein System mit vielen APIs ist nicht automatisch gut integrierbar, wenn Semantik, Versionierung, Betrieb und Herstellerzusagen unklar bleiben.

Governance nach Kritikalität

Nicht jede Schnittstelle benötigt denselben Aufwand. Ein seltener Dateiimport mit manueller Sichtprüfung und einfacher Rücknahme kann schlank dokumentiert werden. Strengere Regeln sind sinnvoll, wenn Vorgänge häufig, finanziell relevant, personenbezogen, schwer rückgängig zu machen oder für einen kritischen Service notwendig sind.

Ein guter Startpunkt sind daher nicht alle vorhandenen Verbindungen. Wählen Sie die Schnittstelle, deren unbemerkter Fehler den größten betrieblichen Schaden auslösen könnte. Prüfen Sie gemeinsam mit Fachbereich und System-Ownern vier Dinge: fachliches Erfolgskriterium, Duplikatschutz, Abgleich und erreichbare Verantwortung. Wenn eine dieser Antworten fehlt, ist die Schnittstelle zwar implementiert, aber noch nicht vollständig als Betriebsprodukt geführt.