Von der allgemeinen Frage zum prüfbaren Qualitätsprozess

Schnittstellen automatisch testen: APIs, Dateien und Legacy-Daten sicher validieren

Warum die Frage zu allgemein ist

Der Begriff Schnittstelle beschreibt zunächst nur eine Grenze zwischen zwei Systemen. Über diese Grenze können HTTP-Requests und -Responses fließen. Es können aber auch Dateien in einem FTP- oder SFTP-Postfach liegen, Nachrichten in einer Queue warten oder Datensätze aus einem alten Host-Export kommen. Jede Variante bringt eigene Fehlerbilder mit.

Die erste Designentscheidung lautet daher nicht „Welches Test-Framework verwenden wir?“, sondern: Welche Eigenschaften einer Übergabe sollen als Vertrag gelten? Erst danach wählen wir Validator, Client und Test-Framework aus. Für CSV und Fixed-Width haben wir diese Frage mit kleinen, formatbezogenen Profilen beantwortet.

Was soll eigentlich getestet werden?

Ein guter automatischer Test lässt sich in Ebenen zerlegen. Das verhindert, dass ein einziger grüner Testlauf zu viel verspricht.

Die ersten beiden Iterationen konzentrieren sich auf Parsing und Struktur. Die übrigen Ebenen bleiben eigenständige Aufgaben für spätere Adapter. Nicht jede Legacy-Datei braucht OAuth, und nicht jede API braucht eine Prüfung des Dateinamens. Eine gemeinsame Ergebnisstruktur soll die Berichte trotzdem vergleichbar halten.

Schnittstellentypen und Startpunkte

Web-APIs, Dateien und Legacy-Exporte sind die drei Anwendungsfelder der Projektidee. Praktisch begonnen haben wir mit einer lokalen JSON-Datei, haben CSV- sowie Fixed-Width-Dateien ergänzt, in Iteration 3 einen begrenzten HTTP-Adapter und in Iteration 4 einen begrenzten SFTP-Adapter umgesetzt. Die folgenden Abschnitte beschreiben, was ein vollständiger Betriebs- und API-Vertrag zusätzlich braucht; Directory-Polling, Mehrdatei-Korrelation und Message-Queue-Adapter bleiben spätere Themen.

1. Web-APIs: Vertrag plus Verhalten

Bei einer HTTP-API ist die Response mehr als ein Datenobjekt. Auch Methode, URL, Header, Statuscode, Laufzeit, Authentifizierung und Fehlerformat gehören zum Vertrag. Ein Schema kann prüfen, ob customerId eine Zeichenkette ist und items ein Array enthält. Es entscheidet aber nicht allein, ob GET /orders/123 bei fehlender Berechtigung mit 403 oder 404 antworten soll.

Für APIs ist deshalb OpenAPI als äußerer HTTP-Vertrag sinnvoll. Die Datenmodelle können darin mit JSON-Schema-kompatiblen Regeln beschrieben werden. Darauf bauen Tests für Statuscodes, Header, Requests und Responses auf. Der Validator ist ein Teil des Contract-Tests – nicht sein Ersatz.

2. Dateien: erst lesen, dann validieren

Eine per FTP oder SFTP bereitgestellte Datei hat Eigenschaften außerhalb ihres Inhalts: Namenskonvention, Ablageort, Lieferfenster, Kompression, Encoding, Prüfsumme und eine Regel für „fertig geschrieben“. Eine valide CSV-Datei kann trotzdem abgeschnitten sein, wenn der Sender sie noch hochlädt und der Empfänger sie zu früh abholt.

Dafür braucht der Datei-Adapter einen klaren Ablauf: Datei finden, Stabilität oder Marker prüfen, sicher übertragen, Hash und Größe dokumentieren, parsen, validieren, in Quarantäne oder Verarbeitung verschieben und das Ergebnis protokollieren.

3. Legacy-Schnittstellen: Vertrag aus Realität und Regeln

Bei alten Schnittstellen existiert das Schema häufig nicht als gepflegte Datei. Dann sind Beispieldaten, DDL-Scripte, Feldbeschreibungen, COBOL-Copybooks, RPG-Quellcode (beispielsweise RPGLE) oder ein bestehender Importer wertvolle Hinweise. Sie liefern aber nicht automatisch die fachliche Wahrheit. Ein Feld kann laut DDL VARCHAR(10) sein und trotzdem nur einen festen Statuscode erlauben.

Die sinnvolle Reihenfolge lautet: einen Schema-Entwurf ableiten, ihn mit der Fachlichkeit abgleichen, bewusst freigeben und als versionierten Vertrag speichern. Die automatische Ableitung spart Arbeit. Sie ersetzt aber nicht die Entscheidung, welche Abweichung ein Fehler und welche eine erlaubte Ausnahme ist.

Welches Schema-Format passt?

Die naheliegenden Formate haben unterschiedliche Rollen. Deshalb sollten sie nicht gegeneinander ausgespielt werden.

Warum JSON Schema unser Startpunkt ist

JSON Schema ist für den Einstieg praktisch, weil Schema und Testdaten beide JSON sein können. Es beschreibt Typen, Pflichtfelder, Arrays, Wertebereiche, Muster und Zusammensetzungen. Das Schema lässt sich versionieren, überprüfen und in vielen Programmiersprachen validieren.

Unser erstes ausführbares Beispiel beschreibt eine Liefermeldung mit Kennung, Menge, E-Mail-Adresse und Lieferadresse. Das Schema gehört zusammen mit seinen Testdaten ins Repository:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "delivery.schema.json",
  "title": "Delivery",
  "type": "object",
  "additionalProperties": false,
  "required": ["deliveryId", "quantity", "email", "address"],
  "properties": {
    "deliveryId": { "type": "string", "minLength": 1 },
    "quantity": { "type": "integer", "minimum": 1 },
    "email": { "type": "string", "format": "email" },
    "address": { "$ref": "refs/address.schema.json" }
  }
}

Die Adresse liegt in einer zweiten Schema-Datei unter refs/address.schema.json. Das vollständige Beispielverzeichnis enthält beide Schemas sowie gültige und fehlerhafte Lieferungen. Die lokale Datei mit quantity: 3 besteht die Prüfung; die Zeichenkette "three" verletzt den vereinbarten Typ.

Ein wichtiges Detail: format ist in Draft 2020-12 nicht automatisch eine verbindliche Prüfung. Wir aktivieren die Format-Assertions ausdrücklich, damit eine offensichtlich fehlerhafte E-Mail-Adresse als Vertragsverletzung gemeldet wird. Eine Erreichbarkeitsprüfung des Postfachs ist das nicht. Hintergrund: Format-Annotation und Format-Assertion.

Entscheidend ist, dass der Vertrag verständlich bleibt: Welche Felder sind Pflicht? Welche zusätzlichen Felder sind erlaubt? Wie streng ist ein Format? Und welche Aussagen gehören gar nicht in das Schema, sondern in eine fachliche Regel? Die Regel „Die Summe aller Positionen muss dem Gesamtbetrag entsprechen“ ist häufig in einer eigenen, gut lesbaren Prüflogik besser aufgehoben.

Architektur: kleiner Kern, offene Anschlüsse

Der aktuelle Stand besteht aus einem Maven-Modul auf Java 21. Der Kern definiert eigene Ergebnisobjekte und eine Validator-Schnittstelle. JSON-, CSV-, Fixed-Width- und HTTP-Adapter kapseln ihre jeweiligen Parser und Profilregeln; die CLI nutzt Picocli. Separate Ausgabe-Bausteine schreiben Text oder JSON. Spring Boot ist dafür derzeit nicht nötig.

Das hält die Bibliotheken austauschbar, macht den Java-Code aber nicht sprachunabhängig. Ein späterer Spring-Boot-Server könnte den Kern einbinden, wenn ein konkreter Anwendungsfall dafür spricht. Die folgende Strecke zeigt, wie vorhandene Dateiadapter und spätere Transportadapter in dieselbe Ergebnisstruktur münden:

Bei einer späteren Erweiterung müssen wir diese Aufgaben sauber zuordnen:

• Quelle: Woher kommen Daten und Metadaten?
• Authentifizierung: Wie wird sie konfiguriert, ohne Geheimnisse in Schema oder Repository zu speichern?
• Lesen: Wie wird eine Antwort oder Datei zuverlässig abgeholt?
• Normalisieren: Wie werden Inhalt, Transportdetails und technische Metadaten zusammengeführt?
• Prüfen: Welcher Strukturvertrag und welche fachlichen Regeln gelten?
• Ergebnis: Wie sieht ein einheitlicher Fehler aus, den Menschen und automatisierte Abläufe gleichermaßen verstehen?

Der aktuelle Ergebnisvertrag bleibt bewusst klein: status, valid und eine sortierte Liste findings. Quelle, Zeitpunkt, Schema-ID, Hash oder HTTP-Metadaten sind mögliche spätere Ergänzungen, keine bereits verfügbaren Felder. Secrets, Tokens und vollständige personenbezogene Nutzdaten gehören grundsätzlich nicht ungefiltert in einen Report.

Dateien automatisch prüfen

Die erste praktische Iteration prüfte eine bereits lokal vorhandene JSON-Datei. Iteration 2 ergänzt lokale CSV- und Fixed-Width-Dateien; Iteration 3 führt einen lokalen HTTP-Aufruf gegen ein Profil aus; Iteration 4 holt genau eine stabile SFTP-Datei ab und validiert sie; Iteration 5 wählt genau eine passende Datei aus einem SFTP-Verzeichnis. Mehrdatei-Lebenszyklen, Claim-/Lock-Protokolle und Betriebsorchestrierung bleiben getrennte Aufgaben.

Zielbild für einen vollständigen Datei-Ablauf

1. Den erwarteten Eingang prüfen: Pfad, Dateiname, Lieferfenster und erlaubte Erweiterung.
2. Erkennen, ob die Datei vollständig geschrieben wurde – etwa über eine temporäre Endung, eine Done-Datei, eine stabile Größe oder eine Prüfsumme.
3. Datei sicher abholen und technische Metadaten erfassen.
4. Encoding und Dateiformat prüfen, bevor die erste Fachregel läuft.
5. Datensätze parsen und gegen das Format-Schema validieren.
6. Fachliche Regeln, Mengen und Dubletten prüfen.
7. Bei Fehlern die Datei unverändert in Quarantäne ablegen und einen nachvollziehbaren Bericht erzeugen.

Für JSON ist genau ein Dokument pro Datei erlaubt; JSONL benötigt weiterhin einen eigenen Ablauf pro Datensatz. CSV und Fixed-Width besitzen inzwischen eigene Version-1-Profile. Die CLI kann das Format ausdrücklich erhalten oder es mit --input-format AUTO aus dem Profilfeld format ableiten. Transport, Dateilebenszyklus und fachliche Mehrdatei-Regeln bleiben davon getrennte Aufgaben.

{
  "format": "csv",
  "version": 1,
  "encoding": "UTF-8",
  "delimiter": ";",
  "header": ["id", "amount", "currency"],
  "columns": [
    { "name": "id", "type": "string", "required": true },
    { "name": "amount", "type": "decimal", "minimum": 0, "maximum": 100000, "required": true },
    { "name": "currency", "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$", "required": true }
  ]
}

Dieses Profil entspricht dem aktuell unterstützten CSV-Vertrag. Ein separates Fixed-Width-Profil beschreibt stattdessen Positionen, Längen und Padding. Die ausführbaren Beispiele, die gemeinsame Validierung und die unterschiedlichen Fehlerfälle zeigt der Subartikel zu Iteration 2.

Web-APIs mit Vertrag und Authentifizierung testen

Der aktuelle API-Adapter konzentriert sich zunächst auf einen bekannten Endpunkt und prüft dabei mehrere Eigenschaften:

• Erreichbarkeit, TLS und Timeout-Verhalten
• korrekte HTTP-Methode, URL, Header und Content-Type
• Authentifizierung und Berechtigungen
• erwartete Statuscodes für Erfolg und definierte Fehlerfälle
• Request- und Response-Schema
• Pagination, Rate Limits, Correlation-ID und Wiederholbarkeit

Bei der Authentifizierung sollte der Test nur ein Profil referenzieren, zum Beispiel oauth2-client-credentials, api-key, mtls oder basic. Die konkreten Werte kommen aus Umgebungsvariablen, einem Secret Store oder einer CI-Konfiguration. Weder der Schema-Entwurf noch ein Test-Report sollte echte Tokens, private Zertifikate oder Passwörter enthalten.

Iteration 3 deckt bereits einen gültigen Request, einen fehlenden oder falschen Request-Wert, einen nicht passenden Status, einen fehlenden Pflicht-Header, einen falschen Response-Typ, kaputtes JSON und einen Transportfehler ab. Berechtigungsprofile, Rate Limits und fachliche Mehrschritt-Szenarien gehören in spätere Iterationen.

Legacy-Schnittstellen nachträglich beschreiben

Ein nachträglich erstelltes Schema ist kein minderwertiger Ersatz für eine offizielle Spezifikation. Es ist häufig der realistischste Weg, um aus implizitem Wissen einen überprüfbaren Vertrag zu machen.

Beispieldaten als Ausgangspunkt

Aus mehreren historischen Dateien lässt sich ein erster Schema-Entwurf ableiten: Welche Spalten kommen immer vor? Welche Werte haben denselben Datentyp? Welche Felder sind gelegentlich leer? Bei nur einem Beispiel wäre die Gefahr groß, Zufälligkeiten als Regeln festzuschreiben. Deshalb sollten Beispiele aus verschiedenen Tagen, Grenzfällen und Fehlerfällen betrachtet werden.

DDL als technischer Hinweis

DDL-Scripte liefern Spaltennamen, Längen, Datentypen, Nullbarkeit und manchmal Schlüssel. Das ist eine gute strukturelle Basis. Sie beantworten aber selten Fragen wie „Darf ein Auftrag den Status X haben?“ oder „Muss die Summe exakt aufgehen?“. Diese Regeln gehören in ein ergänzendes Profil oder in fachliche Tests.

Der Review-Schritt ist Teil der Automatisierung

1. Beispiele und DDL importieren.
2. Den Schema-Entwurf erstellen und unsichere Regeln markieren.
3. Fachliche Eigentümer nach Pflichtfeldern, Codes und Grenzwerten fragen.
4. Gültige und ungültige Fixtures festlegen.
5. Schema als Version 1 freigeben und in die Testläufe aufnehmen.
6. Neue Abweichungen als bewusste Schemaänderung behandeln – nicht als stilles „Anpassen, bis es grün ist“.

Aus Validierung wird Qualitätssicherung

Ein auswertbares Ergebnis muss unterscheiden: Verletzen die Daten den Vertrag, oder konnte die Prüfung gar nicht ordnungsgemäß stattfinden? In Iteration 1 bildet die CLI genau diese Grenze ab.

Die Findings nennen Datenpfad, Schema-Auswertungspfad, Schlüsselwort und Meldung. Ihre Reihenfolge ist fest definiert. Automatisierte Tests können deshalb nicht nur „rot oder grün“, sondern auch den tatsächlichen Bericht mit einem erwarteten Beispiel vergleichen.

Für einen späteren Betrieb kommen weitere Fragen hinzu: Welche Lieferung wurde erwartet? Welche Vertragsversion galt? Ist eine Wiederholung sinnvoll? Der aktuelle Bericht beantwortet diese Fragen noch nicht. Auch fachliche Fehler, etwa eine falsche Positionssumme, sind noch keine eigene Prüfschicht.

Die Idee als fortlaufende Project-Page

Der Artikel darf mit dem Projekt wachsen. So bleiben Entscheidungen nachvollziehbar, und auch lehrreiche Irrwege können ihren Platz behalten. Spätere Implementierungen müssen dadurch nicht so wirken, als wäre die endgültige Architektur schon am ersten Tag bekannt gewesen.

Wir halten die Entwicklung in drei Schichten fest: Die Project-Page beschreibt den geltenden Stand. Das Logbuch bildet die Chronik und wird nur um neue Einträge ergänzt. Ein Sub-Artikel entsteht erst, wenn eine Iteration eigene Beispiele, Ergebnisse oder Fehlversuche mitbringt – nicht als leere Hülle für jede Roadmap-Zeile.

Jede größere Änderung macht drei Dinge sichtbar: Entscheidung, Begründung und Auswirkung. Wenn später ein anderer Validator gewählt wird oder YAML eine eigene Rolle bekommt, ist das kein Bruch der Idee, sondern eine dokumentierte Iteration. Veraltete Aussagen im Artikel werden aktualisiert; das Logbuch bewahrt, warum sie einmal galten.

Erste Entwicklungsiterationen

Das GitHub-Repository ZEUS Interface Quality enthält inzwischen sechs abgeschlossene vertikale Durchstiche. Die folgenden Schritte sind Möglichkeiten, keine Zusage für bereits verfügbare Funktionen:

Repository, CI und der gemeinsame JSON-Bericht bilden weiterhin das Fundament. Iteration 6 bündelt die Verzeichnisauswahl mit Liefer-ID, Claim, Wiederanlauf, Erfolgsarchiv und Quarantäne. Der SFTP-Adapter prüft damit nicht nur den Inhalt, sondern auch den Übergang der Lieferung durch den Prüfprozess. Als Nächstes können OpenAPI-Ableitung, Secret-Verwaltung, gemischte Mehrdatei-Formate oder fachliche Mehrschrittregeln separat bewertet werden.

Logbuch

Neueste Einträge stehen oben. Frühere Einträge bleiben als damaliger Stand erhalten. Der aktuelle Stand steht in der Übersicht am Anfang; ausführliche Beispiele gehören in die verlinkten Praxisartikel.

Offene Fragen

Diese Liste zeigt, was bewusst noch nicht entschieden ist. Sobald eine Frage beantwortet ist, wandert die Entscheidung ins Logbuch und in den geltenden Stand – die Liste wird dann kürzer.

• Welche konkrete OpenAPI- oder Secret-Management-Erweiterung wäre der nächste klar begrenzte HTTP-Schritt?
• Welche Kontextinformationen braucht der Bericht im Betrieb, ohne den bestehenden Vertrag unnötig zu erweitern?
• Welche Grenzen für Dateigröße, Laufzeit und Ressourcen benötigen wir vor einem produktiven Einsatz?
• Wann bekommt YAML einen eigenen Vertrag – und wann reicht „parsen, dann gegen JSON Schema prüfen“?
• Welches Quarantäne- und Retry-Modell gilt als Mindeststandard für Datei-Adapter?
• Welche Lizenz soll für den ersten öffentlichen Release gelten?

Bereits entschieden sind Java 21 als Basis, Text und JSON als Ausgabeformate, der gemeinsame Ergebnisvertrag, eigene Profile für CSV und Fixed-Width sowie das lokale HTTP-Profil mit Request-/Response-Schemas. Unser Lieferbeispiel verbietet zusätzliche Felder beziehungsweise Spalten ausdrücklich; das ist keine globale Vorgabe für jede Schnittstelle.

Was Schema-Validierung nicht leistet

Ein Schema kennt nur Regeln, die darin beschrieben sind. Es kann keine fehlende Fachlichkeit erraten, keine Gegenstelle zur Lieferung bewegen und keinen falsch konfigurierten Benutzerzugang reparieren. Außerdem gibt es Eigenschaften, die absichtlich außerhalb eines reinen Daten-Schemas liegen:

• Verfügbarkeit: Ist der Endpunkt oder das Postfach im Lieferfenster erreichbar?
• Sicherheit: Ist TLS korrekt, wird der Host-Key geprüft und werden Secrets geschützt?
• Performance: Antwortet die API innerhalb der vereinbarten Zeit und unter Last?
• Kompatibilität: Kann ein alter Consumer eine neue, zusätzliche oder entfernte Eigenschaft verarbeiten?
• Fachlichkeit: Passt die Nachricht zum Bestand, zur Reihenfolge und zur Geschäftsregel?
• Betrieb: Werden Retry, Idempotenz, Duplikate und Quarantäne korrekt behandelt?

Gerade diese Grenzen machen die Methode belastbar. Man kann für jede Eigenschaft den passenden Test ergänzen, statt einen einzelnen „Schema-Test“ mit Erwartungen zu überladen.

Glossar

Häufige Fragen