Catching a Breaking API Change Before It Ships, Not After

In a traditional integration test, the producer decides what to verify, which means it tests what the producer assumes matters, not necessarily what consumers actually use. A consumer-driven contract has each consuming service publish exactly what it depends on, specific fields, specific response shapes, and the producer's CI checks changes against that published expectation.

This catches a class of break that producer-only testing structurally misses: a field the producer considered unimportant enough to remove, that one consumer was quietly relying on the whole time.

A contract test that runs after deployment is really just fast incident detection, which is better than nothing but still means the break already happened. Running the check in CI, against the producer's proposed change before it merges, catches the break at the cheapest possible point, before it ever reaches a shared environment.

This requires the consumer's contract to be accessible to the producer's pipeline, typically through a shared contract broker or repository, so a producer's CI run can pull in what every known consumer expects without manual coordination.

A contract that asserts the entire response shape, every field, every value, breaks on any unrelated change and quickly becomes something engineers route around rather than trust. A contract that asserts only what the consumer actually uses, the three fields it reads, not the ones it ignores, stays stable through unrelated changes and only fails when something the consumer genuinely depends on actually changes.

This discipline is what keeps contract testing sustainable at scale. A team that over-specifies its contracts ends up with tests that fail constantly for reasons unrelated to real breaks, which trains everyone to ignore the failures entirely.

Say an inventory service plans to remove a deprecated `legacy_sku` field from its product response, confirmed unused by every consumer the team could think of. Running the change against published contracts in CI surfaces one consumer, a reporting job nobody thought to ask, that still reads that exact field for a legacy report.

The change is held, the reporting job is updated to read the replacement field, and the field removal ships cleanly a week later with zero surprised consumers. Without contract testing, this same change would likely have shipped and broken the reporting job silently, discovered only when someone noticed a report was missing data.

• Contracts written once at setup and never updated as a consumer's actual usage changes
• Overly broad contracts that assert fields the consumer doesn't actually use, causing brittle false failures
• No shared broker, so producers have no reliable way to discover what consumers currently expect
• Contract checks that exist for some service pairs and were never extended to newer ones

Rolling out contract testing across every service pair simultaneously is a slow, resource-heavy project that often stalls before it's useful anywhere. Picking the one producer-consumer relationship that's broken the most in the past, and proving the pattern works there first, builds the case and the internal expertise to extend it elsewhere.

A working contract test on your riskiest integration is worth more than a half-finished rollout attempt across twenty service pairs that never quite gets past the initial setup.

The first instinct when a contract test blocks a merge is often to see it as friction getting in the way of shipping, especially under deadline pressure. Every time that instinct wins and the check gets skipped or the contract loosened just to unblock a release, the whole practice loses credibility for the next failure too.

Treating a failure as real information, either the change genuinely breaks a consumer and needs rework, or the contract is stale and needs updating, keeps the practice trustworthy. The fastest way to kill a contract testing program is letting it become something people route around instead of listen to.