Free learning / 40-minute compatibility lab

Keep old clients working through an API rollout

Execute mixed-version HTTP exchanges, catch a misleading Complete state and defend client/server rollback separately. Give a receiving engineer reproducible evidence.

Begin reading Download a working copy

No account needed. Use your own copy for writing and keep the original as a reference.

Engineering lab library / Run locally

Run the version pairs on your computer.

Download the companion, predict each client/API pairing and compare the actual HTTP response with the action offered to the operator.

Real local HTTP with scripted responses and JavaScript consumer functions. No browser UI, authentication, model or external service; the timeout case returns an authored manual-timeout body.

Start here / Node.js 24 · Offline exercise
Contract rollout · real local HTTP
Compare old and new consumers against actual HTTP responses; preserve manual work and expose a removed compatibility branch.
Node.js 24 · Standard library · Loopback only · Synthetic state
Open walkthrough Download file

40-minute engineering lab · Node.js 24 · Standard library · Original synthetic case

An API deployment does not update every consumer. An operator may keep an old tab open while a new server starts returning a new result. In this lab, a correctly withheld draft becomes a misleading Complete message in the old client. You will reproduce that failure over real local HTTP, preserve a useful fallback, and inspect both rollback directions.

Download the contract-rollout companion. It starts a temporary server on 127.0.0.1, makes requests to that server and closes it. No packages, accounts, model calls or external services are needed. The clients are JavaScript consumer functions with synthetic state, not browser applications. There is no real authentication, sending, data migration or deployment. Server outcomes are authored fixtures: the timeout case returns a manual-timeout body immediately; it does not induce a network timeout. What you execute is the HTTP exchange and the consumer’s resulting state.

1. Learn the three contracts

A producer supplies the response; a consumer interprets it and decides what the person can do next. Wire compatibility concerns communicating and decoding the representation. Semantic compatibility also concerns its meaning and behavior. A response can parse correctly while giving the operator a dangerous impression.

The fictional service helps draft administrative form-location replies. U1 and U2 are consumer versions; A1 and A2 are API implementations. The selected request and unfinished operator note belong to the client state. Neither an API response nor a client upgrade should silently erase that work.

Implementation	Contract in this exercise
A1	Returns a known draft or manual outcome. Ignores the new contract-selection header.
U1	Understands a draft and manual reasons `timeout` / `missing-source`. Its deliberately flawed final HTTP 200 branch says Complete and provides no manual action. Non-2xx responses use its existing unavailable/manual path.
U2	Accepts documented version-1 and version-2 results. Unknown versions, malformed bodies and unknown results use an unavailable/manual path.
Compatible A2	Supplies version 2 only when explicitly selected. Keeps honest version-1 outcomes for old clients; interrupted coverage without version-2 selection returns HTTP 503.

These are deliberately narrow, exact-shape consumer checks. An added field in an otherwise known body also reaches U1’s misleading Complete branch; do not infer tolerant parsing from its age. Other clients may allow extra fields, and need their own demonstrated contract.

X-Training-Contract: 2 is a custom selection field for this exercise. It selects a response representation; it supplies no identity or permission. An unsupported value receives HTTP 400 from compatible A2. This is an explicit fixture policy, not a universal API-versioning standard.

2. Follow the response into the operator state

A2 introduces a distinction between an empty lookup and unavailable source coverage:

Code example

{"contractVersion":2,"kind":"manual","reason":"source-unavailable"}

Returning that object on HTTP 200 to U1 reaches its unknown-result branch. The API withheld the draft, but the client reports Complete. Adding a response enum can therefore break the task even when serialization succeeds.

A compatible server does not rename unavailable coverage to missing-source or timeout merely to fit the old enum. In this fixture, HTTP 503 takes the old client's already-supported unavailable state and exposes manual lookup. U2 can request version 2 and explain the new reason. A supported draft remains a proposal for operator review, never permission to send.

The visual below is an authored interpretation of the cases. Compare it with the output you execute. HTTP 503 is useful here because U1's fallback is known; a real client that loses work on non-2xx would need another verified transition.

UNDERSTAND THE SYSTEM

A valid response can still break the operator's task

Follow one response from version selection to the action offered by the consumer. These authored case interpretations accompany the real loopback HTTP companion; they are not live telemetry.

FOLLOW THE WORK

Watch one example, step by step.

5 authored stepsYou control the pace

01 / EXPLORE THE PARTSTap a part to explain it

Direction of information or workReturn / feedback

Read the connections in plain English

01
Consumer version → Contract selection
The old client sends no new selection; the new client explicitly requests version 2.
02
Contract selection → API producer
A1 ignores the added header; compatible A2 handles supported selections explicitly.
03
API producer → HTTP status + body
A2's compatibility branch chooses an honest representation or the documented unavailable path.
04
HTTP status + body → Consumer branch
The consumer chooses behavior using status and validated fields.
05
Consumer branch → Operator's next action
Observe the action offered, not only whether the body parsed.

Check your understanding: The old client erases work on HTTP 503. Can you reuse this migration unchanged?

No. The compatible path depends on the consumer preserving useful manual work. Verify a repaired consumer or another supported transition before exposing the new result. The status code alone cannot make the workflow compatible.

3. Predict and run the version pairs

← Back to lab library Download Contract rollout · real local HTTP ↓

Read the downloaded file, then run it from your own working folder:

Code example

node --version
node fde-contract-rollout.mjs --all > original-results.json

Before execution, predict the HTTP status, operator state and manual-action availability for each row. Afterward, add the observed response and whether the request and unfinished note survived. Keep a mismatch with your first prediction.

Case	Pair and input	Prediction to write first
`legacy-timeout`	U1 / A1; timeout	Does manual work remain available?
`broken-overlap`	U1 / unadapted A2; interrupted coverage	Which consumer branch handles the new HTTP 200 body?
`server-rollback`	U2 / A1; timeout	Can the new reader still understand the old producer?
`client-rollback`	U1 / compatible A2; interrupted coverage	Does the new producer still support the old reader?
`explicit-v2`	U2 / compatible A2; interrupted coverage	Which header and response identify the selected representation?
`supported-v2`	U2 / compatible A2; supported draft	Is the next action review or automatic sending?
`unsupported-selection`	U2 / compatible A2; unsupported contract	Is the selection rejected while preserving manual work?

To inspect one exchange:

Code example

node fde-contract-rollout.mjs client-rollback
node fde-contract-rollout.mjs server-rollback

Trace selection → actual HTTP status/body → consumer interpretation → retained work. The two rollback cases execute mixed-version pairings. They do not perform a rolling deployment or prove recovery of database changes. Their value is exposing a compatibility assumption before the team relies on it.

Expected interpretation after you have predicted: the deliberately broken overlap reports Complete without manual action. The compatible old-client coverage case uses 503 and keeps manual lookup. The newer client reads A1's known timeout after server rollback and reads A2's explicit version-2 manual reason. Unsupported selection stays unavailable. The supported draft remains reviewable. Compare actual output rather than copying these expectations as run evidence.

4. Break one compatibility control

Use the companion's deliberate fault switch and retain the new output separately:

Code example

node fde-contract-rollout.mjs --all --break-compatibility > changed-results.json

This removes compatible A2's old-client coverage fallback. Predict which row changes. Compare client-rollback with explicit-v2: the old client now receives the new HTTP 200 body and reaches Complete; the explicit version-2 consumer should behave as before. An all-new-client demonstration would miss the regression.

Explain the smallest repair: restore the representation boundary for consumers that did not select version 2. Do not weaken U2's validation or mislabel the source failure. Rerun the affected pair against the original behavior, keeping both outputs and the fault-switch setting. You observed a controlled local fault, not a production incident.

5. Make the receiving team own the next check

In a three-person pod, assign API owner, consumer owner and receiving engineer. Each person predicts a different pair before discussing it. The receiver runs one rollback pair and the changed-control case without the author navigating. Record hints or takeover. For solo work, label the receiving check self-review.

Text example

Candidate file / version or digest:
Pair and fault-switch setting:
My original prediction:
Observed request selection / status / body:
Consumer state / manual action / retained request and note:
My contribution and assistance received:
Receiver action actually performed:
Accept for this stated purpose, or return this specific gap:
Next owner / next check / evidence still missing:

The API owner must define the supported overlap and how to stop exposing the new representation. The consumer owner must verify unknown-result behavior and preservation of real unsaved work. The receiving engineer must locate the exact candidate and reproduce both rollback pairings. The client workflow owner decides whether the fallback is usable for the agreed task. A pod lead coordinates these responsibilities; they do not inherit them from a successful command.

Before retiring version 1, identify active integrations, long-lived tabs, queued work and clients outside your release control. Establish an agreed migration path and receiving-owner evidence. Elapsed time and a successful new-client screenshot are insufficient. For this lab, report only local HTTP and consumer-function observations; browser usability, authorization, live-user impact and placement readiness remain unestablished.

6. Explain, debug and extend

Explain: Why can a new response enum break an otherwise valid API response? Name the producer change and the exact consumer branch.

Debug: A team tests only U2/A2 and says rollback is safe. Identify the two missing pairings and the evidence each would supply. Explain why server rollback and client rollback are different checks.

Design: The real old client erases unsaved work on HTTP 503. Which assumption in this exercise no longer holds? Propose a transition with a verified usable path before exposing the new result. Do not prescribe 503 as the answer when its consumer behavior is the defect.

Continue in the deployment and handoff lesson under existing Academy access. Add the results to the client-delivery workbook alongside the rollout agreement and receiving-team runbook.

Sources and scope

Original LockedIn Labs case and code. References checked 25 October 2026:

Google AIP-180: backwards compatibility distinguishes compatibility dimensions and cautions that consumers can mishandle new response enum values.
AWS Builders' Library: ensuring rollback safety during deployments explains why protocol transitions must remain usable across mixed versions and reversal.
RFC 9110: HTTP semantics defines HTTP status semantics. The custom header and fallback mapping are this exercise's declared contract.

These are learning references, not vendor affiliation or certification. Completion of this exercise is practice evidence, not independent qualification or approval to operate a client system.