Catching a Breaking API Change Before Your Customer Does

A contract test isn't a full integration test against a live dependency, and it isn't just a unit test against a mock either. It verifies that the shape of a request or response, field names, types, which fields are required, matches an agreed contract that both sides can check independently. The provider service confirms its real responses match the contract; the consumer confirms its assumptions match the same contract. Neither side needs the other running to test against, which is what makes this practical to run on every commit instead of only in a slower, shared staging environment.

This independence is the whole point. A traditional integration test that spins up both services together is slow, flaky, and often skipped locally because of the setup overhead; a contract test runs in milliseconds against a stored schema, so there's no excuse for it not being part of every single commit's normal feedback loop.

Contract testing tends to get adopted for third-party integrations, where a breaking change from an external partner feels like an obvious risk, and skipped for internal service-to-service calls, where it feels unnecessary since "we control both sides." In practice, internal services drift apart just as often, a team refactors a response shape without realizing three other internal consumers depend on the old one, and internal breakage is arguably more dangerous precisely because it's not being watched for the way an external integration is.

A consumer-side test built against a hand-maintained fixture representing the provider's response is only as good as how recently that fixture was updated. If the provider changes its actual response shape and nobody remembers to update the fixture, the consumer's tests keep passing against data that no longer reflects reality, which is a false sense of safety that's arguably worse than having no test, since it actively suggests everything's fine.

This is exactly the gap that tends to surface during an incident review after a breaking change reaches production despite a green test suite. The postmortem usually finds the same root cause: a fixture last updated months earlier, quietly diverging from the real contract a little more with each unrelated change on the provider's side, until the gap was wide enough to break something real.

You don't need a dedicated contract-testing framework to get most of the benefit. Generate a schema from the provider's actual response in a scheduled or CI-triggered test, and diff it against the consumer's expected schema, failing the build on a mismatch. This catches the majority of breaking changes, missing fields, changed types, newly required fields, without requiring both teams to adopt new tooling or rewrite existing tests.

Start with your two or three highest-traffic internal integrations rather than trying to cover everything at once. A schema diff script that takes an afternoon to write and covers your riskiest dependency delivers more real protection than a comprehensive framework rollout that's still half-finished six months later because it tried to cover every integration in the company from day one.

• Generate the provider's real response schema as part of its own CI run
• Store that schema somewhere the consumer's CI can fetch and diff against
• Fail the consumer's build on a mismatch, before the change ships anywhere near production
• Apply this to internal service-to-service calls, not just external partner integrations