A local profile connects request, transport, and response contract

Automatically Test HTTP Interfaces: Status, Headers, and JSON Contracts

The larger approach is covered by the English Project Page. Iteration 1 explains the JSON contract, and Iteration 2 covers CSV and fixed-width files. This article shows the HTTP slice and its boundaries.

The HTTP profile as a local contract

The profile describes only what this adapter can actually check. It is intentionally smaller than OpenAPI: method, URL, headers, status, and JSON schemas are enough for a first reproducible HTTP proof.

{
  "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
}

The schema paths are relative local files. The adapter resolves them below the profile directory and rejects paths that escape through .. or symbolic links. The URL may not contain credentials or a fragment. Header names must be valid HTTP token names, and header values may not contain line breaks.

These rules are not a complete security architecture, but they stop a profile from silently pointing to arbitrary local files or carrying credentials in a URL.

Validate the request before sending

If the profile defines requestSchema, a local input file is required. The adapter validates it before calling HttpClient.send. A missing field or wrong type is therefore a request finding, not an ambiguous failure of the counterparty.

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

A request violation is mapped into the shared report with an explicit side:

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

The message is useful for people, but automation should use status, paths, and keyword. The important side effect is that an invalid request is rejected before it is sent; the loopback test verifies that the local server receives no request in this case.

Execute the HTTP request reproducibly

The transport uses the JDK HTTP client, so no extra client library or Spring Boot runtime is needed. Method, URL, headers, and timeout come from the profile. Redirects are disabled, making an unexpected target change visible rather than silently following a second request.

$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

A real local run needs an endpoint with the expected behavior on the port in the profile. The automated tests use a loopback server rather than a public service, so status, headers, and response body stay under test control and no external system is affected.

Check status, headers, and response schema

A response is contract-compliant only when several layers match. The adapter reports them separately: unexpected status under /response/status, missing headers under /response/headers/, and schema findings under /response/body/....

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

Content type is compared as a media type, ignoring parameters such as charset=utf-8. The body is decoded strictly as UTF-8 and parsed as JSON. A malformed JSON response is therefore an invalid response contract with exit code 1; an unreachable server is a technical failure with 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"
  } ]
}

The report does not contain the complete response payload or request header values. That keeps the first report contract small and reduces the chance of tokens, personal data, or large response bodies leaking into CI logs.

Read findings and exit codes

The distinction matters in CI. Exit code 1 means the adapter could classify the data and found a contract violation. Exit code 2 means the check itself could not be trusted.

Why the core stays unchanged

The new adapter implements the same Validator interface as the file adapters. The HTTP-specific code reads the profile, executes the transport, and maps deviations to Finding objects. The CLI and report writer do not need to know whether a finding came from a JSON file or an HTTP response.

The automated evidence

The new tests start a local loopback server and cover more than the happy path: a valid request and response, an invalid request that must not be sent, wrong status, missing header, wrong response type, malformed response JSON, the real CLI output, and a transport failure.

The tests remain local: they need no public endpoint, send no data to the internet, and control the expected status and headers. That proves the adapter; it does not prove availability or business correctness of a production API.

What is deliberately not included

• no OpenAPI parser and no automatic profile generation from OpenAPI;
• no OAuth, API-key, or mTLS secret management;
• no redirects, streaming, multi-step calls, or multi-file scenarios;
• no SFTP or FTP connection, quarantine, or retry model;
• no business rules across multiple requests or records;
• no performance, load, or availability claim about a real API.