Ein lokales Profil bringt Request, Transport und Response-Vertrag zusammen

HTTP-Schnittstellen automatisch testen: Status, Header und JSON-Verträge

Die übergeordnete Idee steht im Hauptartikel zur automatischen Schnittstellenqualität. Die erste Iteration erklärt JSON Schema als lokalen Prüfvertrag, Iteration 2 zeigt CSV und Fixed-Width. Hier geht es nun um den HTTP-Strang – und ebenso um die Grenzen, die ihn in dieser Ausbaustufe bewusst klein halten.

Das HTTP-Profil als lokaler Vertrag

Das Profil beschreibt nur Regeln, die der Adapter in dieser Iteration tatsächlich prüfen kann. Es ist absichtlich kleiner als OpenAPI: Methode, URL, Header, Status und JSON-Schemas reichen für einen ersten reproduzierbaren HTTP-Nachweis. Gerade diese Begrenzung macht den Ablauf gut lesbar.

{
  "format": "http",
  "version": 1,
  "method": "POST",
  "url": "http://127.0.0.1:8080/deliveries",
  "requestHeaders": {
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  "requestSchema": "delivery-request.schema.json",
  "expectedStatus": 201,
  "requiredResponseHeaders": ["Content-Type", "X-Request-Id"],
  "responseContentType": "application/json",
  "responseSchema": "delivery-response.schema.json",
  "timeoutSeconds": 5
}

Die beiden Schemaangaben sind relative lokale Pfade. Der Adapter löst sie unterhalb des Profilverzeichnisses auf und verwirft Pfade, die durch .. oder Symlinks aus diesem Bereich herausführen. Die URL darf Credentials und Fragmente nicht enthalten. Header-Namen werden als HTTP-Token geprüft, Header-Werte dürfen keine Zeilenumbrüche enthalten.

Das ist keine vollständige Sicherheitsarchitektur – soll es auch nicht sein. Die Regeln verhindern aber zwei typische Überraschungen: Ein Testprofil zeigt nicht stillschweigend auf beliebige lokale Dateien, und geheime URL-Bestandteile wandern nicht unbemerkt in die Konfiguration.

Request vor dem Versand prüfen

Wenn das Profil ein requestSchema nennt, ist auch eine lokale Eingabedatei erforderlich. Der Adapter validiert sie, bevor er HttpClient.send aufruft. Ein fehlendes Pflichtfeld oder ein falscher Typ bleibt damit ein sauberer Request-Befund – und wird nicht mit einem Fehler der Gegenstelle vermischt.

{
  "deliveryId": "DEL-1001",
  "quantity": 3,
  "email": "ops@example.org"
}

Eine Request-Schema-Verletzung landet im gemeinsamen Report. Die Pfade machen dabei ausdrücklich sichtbar, auf welcher Seite die Abweichung liegt:

{
  "status" : "INVALID",
  "valid" : false,
  "findings" : [ {
    "instancePath" : "/request/body/quantity",
    "schemaPath" : "/request/schema/properties/quantity/type",
    "keyword" : "type",
    "message" : "should be integer"
  } ]
}

Der konkrete Meldungstext hilft beim Lesen, ein Automatisierungsskript sollte jedoch auf status, Pfade und keyword reagieren. Wichtig ist außerdem der Seiteneffekt: Ein ungültiger Request wird vor dem Versand abgewiesen. Der Loopback-Test von Iteration 3 macht das sichtbar, indem der lokale Server in diesem Fall keinen Request empfangen darf.

Die HTTP-Anfrage reproduzierbar ausführen

Der Transport basiert auf dem JDK-HTTP-Client und braucht deshalb weder eine zusätzliche Laufzeitbibliothek noch Spring Boot. Methode, URL, Header und Timeout kommen aus dem Profil. Die Standardkonfiguration folgt keinen Redirects. So bleibt ein unerwarteter Wechsel des Zielpfads ein sichtbarer Fehler – statt zu einem stillen zweiten Aufruf zu werden.

$jar = "target/zeus-interface-quality-0.1.0-SNAPSHOT.jar"
$profile = "src/test/resources/fixtures/http/delivery.http-profile.json"
$input = "src/test/resources/fixtures/http/delivery-request.json"

java -jar $jar validate --input-format http --schema $profile --input $input --report json
$LASTEXITCODE

Für einen echten lokalen Lauf muss auf dem im Profil genannten Port ein HTTP-Endpunkt mit dem erwarteten Verhalten lauschen. Die automatisierten Tests nehmen dafür keinen öffentlichen Dienst, sondern einen lokalen Loopback-Server. Status, Header und JSON-Body bleiben so reproduzierbar, und der Test erzeugt keine externe Nebenwirkung.

Status, Header und Response-Schema prüfen

Eine Response ist erst dann vertragskonform, wenn mehrere Ebenen passen. Der Adapter hält die Abweichungen getrennt fest: Ein falscher Status landet unter /response/status, fehlende Pflicht-Header unter /response/headers/<name> und Schemaabweichungen unter /response/body/....

{
  "accepted": true,
  "deliveryId": "DEL-1001",
  "requestId": "req-local-1001"
}

Der Content-Type wird als Media-Type verglichen; Parameter wie charset=utf-8 ändern nicht die Bewertung von application/json. Der Body wird strikt als UTF-8 decodiert und danach als JSON geparst. Eine kaputte JSON-Antwort ist deshalb eine Response-Vertragsverletzung mit Exit-Code 1. Ein nicht erreichbarer Server dagegen ist ein technischer Fehler mit Exit-Code 2.

{
  "status" : "INVALID",
  "valid" : false,
  "findings" : [ {
    "instancePath" : "/response/status",
    "schemaPath" : "/expectedStatus",
    "keyword" : "status",
    "message" : "HTTP-Status 201 erwartet, 500 erhalten"
  }, {
    "instancePath" : "/response/headers/X-Request-Id",
    "schemaPath" : "/requiredResponseHeaders",
    "keyword" : "required",
    "message" : "HTTP-Response enthält den erforderlichen Header nicht: X-Request-Id"
  }, {
    "instancePath" : "/response/body/accepted",
    "schemaPath" : "/response/schema/properties/accepted/type",
    "keyword" : "type",
    "message" : "should be boolean"
  } ]
}

Der Report enthält weder die vollständige Response-Payload noch Request-Header-Werte. So bleibt die erste Report-Schnittstelle klein, und das Risiko sinkt, dass Tokens, personenbezogene Daten oder große Antwortkörper in CI-Logs landen.

Findings und Exit-Codes lesen

Diese Trennung ist im CI entscheidend. Exit-Code 1 bedeutet: Der Adapter konnte die Eingabe prüfen beziehungsweise die Schnittstelle erreichen, aber der Vertrag ist verletzt. Exit-Code 2 bedeutet: Die Prüfung selbst konnte nicht zuverlässig durchgeführt werden.

Warum der Kern unverändert bleibt

Der neue Adapter spricht dieselbe Validator-Schnittstelle wie die lokalen Datei-Adapter. Sein HTTP-spezifischer Teil liest das Profil, führt den Transport aus und übersetzt Abweichungen in Finding-Objekte. CLI und Report müssen dadurch nicht wissen, ob ein Befund aus einer JSON-Datei oder aus einer HTTP-Response stammt.

Der automatisierte Nachweis

Die neuen Tests starten einen lokalen Loopback-Server und bleiben nicht beim Happy Path stehen. Der Testbestand deckt einen gültigen Request mit Response, einen ungültigen Request ohne Versand, falschen Status, fehlenden Header, falschen Response-Typ, kaputtes Response-JSON, die echte CLI-Ausgabe und einen nicht erreichbaren Transport ab.

Die Tests bleiben absichtlich lokal. Sie benötigen keinen externen Webdienst, senden keine Daten ins Internet und können erwarteten Status und Antwort-Header vollständig kontrollieren. Das ist ein belastbarer Nachweis für den Adapter – aber noch kein Beweis für die Verfügbarkeit oder Fachlichkeit einer produktiven Gegenstelle.

Was bewusst noch nicht enthalten ist

• kein OpenAPI-Parser und keine automatische Ableitung eines Profils aus einer OpenAPI-Datei;
• keine OAuth-, API-Key- oder mTLS-Verwaltung und keine Secret-Quelle;
• keine Redirects, kein Streaming und keine Mehrschritt- oder Mehrdatei-Szenarien;
• keine SFTP- oder FTP-Verbindung, keine Quarantäne und kein Retry-Modell;
• keine fachlichen Regeln über mehrere Requests oder Datensätze;
• keine Performance-, Last- oder Verfügbarkeitsaussage über eine reale API.

Diese Grenzen gehören zur Iteration; sie sind nicht bloß eine To-do-Liste. Ein kleiner HTTP-Vertrag mit lokaler Reproduzierbarkeit liefert bereits einen prüfbaren Baustein. Authentifizierung, OpenAPI und Betriebsverhalten kommen erst hinzu, wenn ein konkreter Anwendungsfall die zusätzlichen Regeln rechtfertigt.