Eine gute Softwareschnittstelle überträgt nicht nur Daten. Sie bildet einen verständlichen und betreibbaren Vertrag zwischen Quelle und Verbraucher: Bedeutung, Voraussetzungen, Verhalten, Fehler und Änderungen sind geklärt.
Die konkrete technische Ausprägung kann synchron, dateibasiert oder ereignisorientiert sein. Die grundlegenden Qualitätsmerkmale bleiben ähnlich.
1. Ein klarer fachlicher Zweck
Die Schnittstelle hat eine benannte betriebliche Funktion. Es ist erkennbar, welche Handlung oder Entscheidung sie ermöglicht und welche Folge ein Ausfall hätte.
„Kundendaten synchronisieren“ ist oft zu breit. „Freigegebene Rechnungsadresse vor Auftragserstellung bereitstellen“ beschreibt Zweck und Zeitpunkt genauer.
2. Eindeutige Semantik
Feldnamen allein garantieren kein gemeinsames Verständnis. Definiere:
- fachliche Bedeutung,
- Format und Einheit,
- zulässige Werte,
- Pflicht und Optionalität,
- Zeitbezug,
- Regeln für unbekannt, leer oder nicht anwendbar.
Ein Feld Datum kann Bestell-, Liefer-, Leistungs- oder Änderungsdatum meinen. Solche Unterschiede
gehören in den Vertrag.
3. Geklärte Datenführung
Für jede Information ist festgelegt:
- welches System den verbindlichen Stand führt,
- wer ihn fachlich verantwortet,
- welche Seite Änderungen auslösen darf,
- wie Konflikte behandelt werden,
- ob und wann Rückmeldungen zurückfließen.
Wechselseitige Synchronisation ist besonders anspruchsvoll und sollte nur eingesetzt werden, wenn beide Änderungsrichtungen fachlich nötig und konfliktfähig gestaltet sind.
4. Passende Kopplung
Die Schnittstelle passt zeitlich und technisch zum Prozess:
- synchron, wenn eine unmittelbare Antwort für die Handlung benötigt wird,
- asynchron, wenn Entkopplung, Lastverteilung oder spätere Verarbeitung sinnvoll ist,
- stapel- oder dateibasiert, wenn Zeitbezug und Volumen dies erlauben.
„Echtzeit“ ist kein Qualitätsmerkmal an sich. Engere zeitliche Kopplung kann Verfügbarkeit und Fehlerauswirkungen verschärfen.
5. Sichere Wiederholung
Übertragungen können wegen Zeitüberschreitung oder Störung wiederholt werden. Eine gute Schnittstelle verhindert dadurch ungewollte doppelte Aufträge, Zahlungen oder Nachrichten.
Nutze eindeutige fachliche oder technische Schlüssel und dokumentiere, wie Wiederholung, Duplikate und Reihenfolge behandelt werden.
6. Verständliche Fehlerbehandlung
Unterscheide mindestens:
- fachlich ungültige Daten,
- fehlende Voraussetzungen,
- vorübergehende technische Störung,
- dauerhafte Nichtverfügbarkeit,
- Berechtigungsfehler,
- Konflikt durch parallele Änderung.
Für jede Fehlerklasse braucht es eine angemessene Reaktion: ablehnen, zurückstellen, erneut versuchen, in Klärung geben oder eskalieren.
7. Beobachtbarkeit
Betrieb und Fachverantwortung müssen erkennen können:
- ob die Schnittstelle arbeitet,
- wann zuletzt erfolgreich übertragen wurde,
- wie viele Vorgänge warten oder fehlschlagen,
- welcher konkrete Vorgang betroffen ist,
- ob vereinbarte Zeiten eingehalten werden,
- ob Wiederholungen oder Datenanomalien zunehmen.
Technische Protokolle allein reichen nicht, wenn Fachrollen den betroffenen Auftrag nicht identifizieren können.
8. Angemessene Sicherheit
- eindeutige technische Identität,
- nur erforderliche Berechtigungen,
- geschützte Übertragung,
- sicherer Umgang mit Zugangsdaten und Schlüsseln,
- nachvollziehbare Zugriffe und Änderungen,
- Begrenzung von Menge und Missbrauch,
- Schutz sensibler Inhalte auch in Protokollen und Testdaten.
Sicherheitsanforderungen richten sich nach Daten, Funktion und Risiko der konkreten Verbindung.
9. Beherrschbare Versionierung
Änderungen am Vertrag werden geplant:
- Welche Änderungen bleiben kompatibel?
- Wie werden Verbraucher informiert?
- Können Versionen vorübergehend parallel laufen?
- Wie lange wird eine alte Variante unterstützt?
- Welche Tests verhindern unbeabsichtigte Brüche?
- Wer entscheidet über Umstellung und Abschaltung?
Versionierung ersetzt keine Änderungskoordination. Viele dauerhaft aktive Versionen erhöhen Komplexität.
10. Testbarkeit
Teste nicht nur gültige Beispieldaten:
- fehlende Pflichtwerte,
- unbekannte Referenzen,
- doppelte Nachricht,
- falsche Reihenfolge,
- Zeitüberschreitung,
- Teil- oder Zielsystemausfall,
- Berechtigungsentzug,
- Änderung des Datenvertrags,
- Wiederanlauf nach Störung.
Vertragstests können prüfen, ob Quelle und Verbraucher vereinbarte Strukturen einhalten. Fachliche End-to-End-Tests zeigen, ob der betriebliche Zusammenhang funktioniert.
11. Klare Betriebsverantwortung
Benannt sind:
- fachliche Eigentümerschaft,
- technische Betriebsverantwortung,
- Überwachung und Alarmierung,
- Fehlerannahme und Eskalation,
- Wartungs- und Änderungsfenster,
- Dokumentation und Zugänge,
- Verhalten bei Ausfall,
- Unterstützung durch beteiligte Anbieter.
Eine kompakte Prüfliste
- Zweck und Kritikalität dokumentiert
- Begriffe und Datenvertrag eindeutig
- führende Systeme geklärt
- Übertragungsart angemessen
- Wiederholung und Duplikate beherrscht
- Fehler fachlich bearbeitbar
- Betrieb beobachtbar
- Rechte auf Minimum begrenzt
- Änderungen und Abschaltung geregelt
- Normal-, Ausnahme- und Ausfallfälle getestet
- Verantwortung über Systemgrenzen benannt
Eine gute Schnittstelle maximiert nicht Durchsatz oder technische Eleganz. Sie erfüllt ihren Zweck verlässlich, bleibt bei Störungen handhabbar und kann verändert werden, ohne die verbundene Arbeit unkontrolliert zu gefährden.