Skip to content

CONCEPT Cited by 1 source

Response comparison — headers, body, status

Definition

Response comparison along three axes is the canonical diff framework used in API-level parallel runs: two HTTP responses are compared along HTTP status, the headers set, and the body content. A mismatch on any axis increments the Unmatched counter for that endpoint.

The three axes

1. HTTP status

  • Exact status-code match required.
  • Examples of differences Zalando flags: "2xx and 4xx or even 201 and 200."
  • Status differences often indicate real semantic divergence — old and new systems disagreeing on the outcome of the request (success vs error, created vs updated).

2. Headers

  • Both systems' header sets are compared.
  • Differences can be: a missing header in one response, or different values for the same header.
  • Many headers differ deterministically and must be ignored — Zalando's example: "we ignored some headers that were not relevant for the outcome of the request."
  • Common ignore-list candidates (industry practice, not from the post): Date, X-Request-Id, transfer-encoding, per-framework Server headers, trace IDs.

3. Body

  • Field-by-field JSON (or equivalent) diff.
  • "Missing fields/attributes in the responses or different values for the same field/attribute."
  • Edge cases named in Zalando's post:
  • PDFs — "comparing PDFs might be complicated due to different but negligible metadata."
  • Collections with different ordering — two equivalent sets but ordered differently.
  • HTTP framework change — different default response headers (framework-dependent).

The Matched / Unmatched / Failed triad

Zalando uses three counters per operation_id:

Counter Meaning
Matched Responses matched on all three axes (ignoring tuned-out headers).
Unmatched At least one axis differed.
Failed Transient issue terminated the request (typically 5xx) — "even if they matched it would not be a valuable information given that the request couldn't be properly fulfilled due to a transient server-side issue."

Subtlety: if the request did not match on 5xx cases, the Unmatched counter (not Failed) is incremented, because "it means the overall behavior of the Returns microservice doesn't match the one from the monolith, and it requires a deeper investigation." 5xx concordance is the separator.

Comparator tuning is a first-class activity

"In the comparison check not everything needs to match 100%." Tuning the comparator is part of the parallel-run work:

  • Decide which headers to ignore.
  • Decide how to normalise collection order (sort before comparing).
  • Decide how to compare semi-structured payloads like PDFs (ignore metadata fields, compare rendered content, or compare byte ranges).
  • Handle type-coercion differences (e.g., 123 vs "123" in JSON).

Poor comparator tuning produces spurious Unmatched noise and depresses the match rate below the real equivalence level — making the readiness threshold feel unreachable.

Zalando framing

"Matched: counter for all the requests that matched between the monolith and the Returns microservice."

"Unmatched: counter for all the requests that did not match between the two services. Possible examples could be: Different HttpStatuses: such as 2xx and 4xx or even 201 and 200. Different Headers set: a missing header in one of the two responses or different values for the same header. Different Body responses: missing fields/attributes in the responses or different values for the same field/attribute."

"Failed: counter for all the requests where the response was terminated by temporary issues, such as for example in case of any 5xx." (Source: sources/2021-11-03-zalando-parallel-run-pattern-a-migration-technique-in-microservices)

Failure modes

  • Byte-equality target. Sets the bar too high — natural differences (Date headers, framework defaults, metadata) swamp the signal.
  • No comparator iteration. Initial comparator ships without header ignore-list → everything looks Unmatched.
  • Lump 5xx-concordance into Failed rather than distinguishing matching-5xx from differing-5xx. Loses the signal that one system is failing on inputs the other handles.
  • No per-endpoint comparator override. PDF endpoint needs different rules than a JSON endpoint.

Seen in

Last updated · 550 distilled / 1,221 read