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.

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.

Für die erste Version genügt es, diese Ebenen sichtbar zu machen und pro Adapter nur die passenden Prüfungen zu aktivieren. Nicht jede Legacy-Datei braucht OAuth, und nicht jede API braucht eine Prüfung des Dateinamens. Eine gemeinsame Ergebnisstruktur hilft aber dabei, Berichte unabhängig von der Quelle verständlich zu halten.

Schnittstellentypen und Startpunkte

Die Übersicht oben enthält bewusst auch Message Queues. Für die erste Projektfassung konzentrieren wir uns auf drei Startpunkte: Web-API, Datei und Legacy-Export. Queues kommen später hinzu, sobald der gemeinsame Kern steht.

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.

Ein minimaler Vertrag für eine Liefermeldung könnte zum Beispiel so beginnen:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://tiny-tool.de/schemas/lieferung-v1.json",
  "title": "Lieferung",
  "type": "object",
  "required": ["messageId", "createdAt", "records"],
  "properties": {
    "messageId": { "type": "string", "minLength": 1 },
    "createdAt": { "type": "string", "format": "date-time" },
    "records": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": ["id", "amount", "currency"],
        "properties": {
          "id": { "type": "string", "pattern": "^[A-Z0-9-]+$" },
          "amount": { "type": "number", "minimum": 0 },
          "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }
        },
        "additionalProperties": false
      }
    }
  },
  "additionalProperties": false
}

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.

Die geplante Architektur

Der Kern des Projekts soll für jeden neuen Schnittstellentyp wiederverwendbar bleiben. Er übernimmt die gemeinsamen Schritte; Adapter kümmern sich um die jeweiligen Unterschiede.

Intern sollte jeder Adapter dieselbe grobe Schnittstelle anbieten:

• 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?

Ein Ergebnis sollte mindestens Quelle, Zeitpunkt, Schema-ID, Status und konkrete Fehlerdetails enthalten. Für Dateien kommen Dateiname, Größe und Hash hinzu. Für APIs sind HTTP-Methode, Endpunkt, Statuscode und eine Request- oder Correlation-ID hilfreich. Secrets, Tokens und vollständige personenbezogene Nutzdaten gehören nicht ungefiltert in den Report.

Dateien automatisch prüfen

Für die erste praktische Iteration sind bereitgestellte Dateien ein gutes Ziel. Sie lassen sich reproduzierbar testen, als Testartefakte versionieren und zeigen schnell, welchen Nutzen ein Schema hat.

Der Prüfablauf für Datei-Schnittstellen

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 und JSONL kann der JSON-Schema-Validator direkt auf den geparsten Daten arbeiten. Bei CSV oder Fixed-Width braucht der Adapter zusätzlich Informationen wie Trennzeichen, Header-Regel, Spaltenposition, Encoding und Dezimalformat.

{
  "kind": "file",
  "format": "csv",
  "encoding": "UTF-8",
  "delimiter": ";",
  "header": ["id", "amount", "currency"],
  "columns": {
    "id": { "type": "string", "required": true },
    "amount": { "type": "decimal", "minimum": 0, "required": true },
    "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "required": true }
  }
}

Das ist kein Versuch, CSV in JSON umzubenennen. Es ist ein konkretes Adapter-Profil, das CSV korrekt liest und dieselben verständlichen Fehlerdetails liefern kann: „Zeile 18, Spalte amount: Dezimalwert ungültig“ oder „Header currency fehlt“. Genau diese Übersetzung macht unterschiedliche Schnittstellen vergleichbar.

Web-APIs mit Vertrag und Authentifizierung testen

Der API-Adapter kann sich auf einen bekannten Endpunkt konzentrieren und trotzdem mehrere Prüfungen durchführen:

• 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.

Für den Start reichen wenige repräsentative Szenarien: ein gültiger Request, ein fehlendes Pflichtfeld, ein ungültiger Typ, ein nicht berechtigter Zugriff und ein definierter Serverfehler. So wird nicht nur der grüne Happy Path automatisiert.

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 Validator liefert zunächst Pass oder Fail. Für den Betrieb brauchen Menschen und Automatisierung aber mehr Kontext. Ein brauchbarer Bericht beantwortet mindestens vier Fragen:

1. Was wurde geprüft? Quelle, Datei, Endpunkt, Testlauf und Umgebung.
2. Gegen welchen Vertrag? Schema-ID, Version und Adapter-Profil.
3. Was ist fehlgeschlagen? Fehlercode, Pfad, Zeile, Datensatznummer und verständliche Meldung.
4. Was soll als Nächstes passieren? Wiederholen, Quarantäne, fachliche Prüfung oder Schema-Änderung.

Besonders wertvoll ist die Trennung von technischem und fachlichem Fehler. Wenn eine Datei syntaktisch sauber ist, aber die Summe nicht stimmt, hilft ein anderer Ansprechpartner als bei einem kaputten Encoding. Die gleiche Unterscheidung macht CI-Checks und Monitoring aussagekräftiger.

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 folgt bewusst später. Für die Initialplanung teilen wir die Entwicklung in kleine, demonstrierbare Schritte:

Die Reihenfolge ist kein Dogma. Wenn ein konkretes Vorhaben zuerst SFTP benötigt, kann Iteration 4 vorgezogen werden. Wichtig ist, den Kern klein zu halten und jede Erweiterung an einem realistischen Beispiel zu beweisen.

Logbuch

Neueste Einträge stehen oben. Ein Eintrag ist kurz: Was wurde entschieden oder gebaut, warum, und was ändert sich an der geltenden Idee? Lange Belege, Code und Fixtures gehören später in einen Sub-Artikel.

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.

• In welcher Sprache startet das erste Testprogramm – klein und lokal reproduzierbar oder direkt für die CI vorbereitet?
• Ist das maschinenlesbare Ergebnis eigenes JSON, SARIF, HTML oder zuerst nur strukturierte Konsole?
• Wie streng sollen unbekannte Felder behandelt werden: verbieten, warnen oder typspezifisch konfigurieren?
• 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?

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