Schnittstellen dokumentieren, bevor sie brechen
Eine Schnittstelle ist dokumentiert, wenn jemand ohne Vorwissen den Fehlerfall nachstellen kann. Alles andere ist eine Beschreibung — und die hilft um drei Uhr nachts nicht.
Jede Integration funktioniert am Tag der Abnahme. Interessant wird sie zwei Jahre später, wenn sie ausfällt und die Person, die sie gebaut hat, nicht mehr im Haus ist.
Was hineingehört
Zweck in einem Satz. „Überträgt bezahlte Bestellungen aus dem Shop in die Warenwirtschaft." Klingt trivial, fehlt erstaunlich oft.
Auslöser und Richtung. Wer ruft wen? Zeitgesteuert oder ereignisbasiert? In welchem Takt?
Felder und ihre Bedeutung. Nicht nur die Liste, sondern die Zuordnung: Was wird woraus, welche Umrechnung passiert, welches Feld ist Pflicht.
Fehlerfälle. Was passiert bei Zeitüberschreitung, bei ungültigen Daten, bei doppelter Lieferung? Und vor allem: Was passiert danach — Wiederholung, Warteschlange, Meldung?
Was regelmäßig fehlt
Wer ist Eigentümer? Nicht wer es gebaut hat, sondern wer heute entscheidet, ob eine Änderung gemacht wird.
Wo liegen die Zugangsdaten? Nicht die Daten selbst — der Ort und der Weg, sie zu erneuern. Ein abgelaufener Zugang ist eine der häufigsten Ursachen für stillstehende Ketten.
Was passiert bei Ausfall? Läuft der Shop weiter? Stauen sich Bestellungen? Gehen sie verloren? Diese drei Fälle sind sehr verschieden, und die Antwort muss vorher feststehen.
Wer wird benachrichtigt? Eine Meldung an ein Postfach, das niemand liest, ist keine Meldung.
Die Probe
Geben Sie die Dokumentation jemandem, der das System nicht kennt, und lassen Sie ihn eine Aufgabe erledigen:
„Die Übertragung steht seit gestern. Finde heraus, woran es liegt, und stelle den Fehler in einer Testumgebung nach."
Gelingt das in einer Stunde, ist die Schnittstelle dokumentiert. Gelingt es nicht, haben Sie eine Beschreibung — die im Normalbetrieb vollkommen genügt und im Fehlerfall wertlos ist.
Wo es in Shopware konkret wird
Ein Beispiel, das zeigt, wie viel Protokoll wert ist: Shopware hält für Webhooks je Zustellversuch fest, was gesendet und was geantwortet wurde, inklusive Status und Antwortzeit. Wer das kennt, findet die Ursache eines fehlgeschlagenen Aufrufs in Minuten — wer es nicht kennt, rätselt. Die Einzelheiten stehen in Webhooks in Shopware 6.
Für ausgehende Ketten gilt dasselbe in die andere Richtung: Eine Automation, die still stehenbleibt, ist schlimmer als keine. Wie man das verhindert, haben wir am Beispiel Make beschrieben.
Der Umfang, den wir empfehlen
Eine Seite je Schnittstelle. Wirklich eine Seite:
- Zweck
- Auslöser, Richtung, Takt
- Felder und Zuordnung (Tabelle)
- Fehlerfälle und was dann passiert
- Eigentümer, Zugangsdaten-Ort, Meldeweg
- Datum der letzten Prüfung
Punkt 6 ist der, der aus Dokumentation etwas Lebendiges macht. Ohne ihn weiß niemand, ob die Seite noch stimmt.
Warum das gerade jetzt wichtiger wird
Mit KI-Assistenten, die über Protokolle wie MCP auf Systeme zugreifen, wächst die Zahl der Verbindungen — und damit die Zahl der Stellen, an denen etwas stillschweigend anders läuft als gedacht. Was das Protokoll ändert und was nicht, haben wir hier eingeordnet.
