{"id":2772,"date":"2026-06-08T04:28:01","date_gmt":"2026-06-08T04:28:01","guid":{"rendered":"https:\/\/tucumandevelopers.com\/index.php\/2026\/06\/08\/contract-testing-catch-breaking-api-changes-before-your-consumers-do\/"},"modified":"2026-06-08T04:28:01","modified_gmt":"2026-06-08T04:28:01","slug":"contract-testing-catch-breaking-api-changes-before-your-consumers-do","status":"publish","type":"post","link":"https:\/\/tucumandevelopers.com\/index.php\/2026\/06\/08\/contract-testing-catch-breaking-api-changes-before-your-consumers-do\/","title":{"rendered":"Contract Testing: Catch Breaking API Changes Before Your Consumers Do"},"content":{"rendered":"
\n
\n
\n

Ever shipped a backend change that passed every test, only to wake up to a frontend on fire? The API still returned 200 OK<\/code> \u2014 it just renamed user_name<\/code> to username<\/code>, and three consumers broke silently. Unit tests didn’t catch it. Integration tests didn’t catch it. This is exactly the gap contract testing<\/strong> fills.<\/p>\n

<\/a> What a contract actually is <\/h2>\n

A contract is a machine-readable agreement about the shape of requests and responses between a consumer<\/strong> (the client) and a provider<\/strong> (the API). Instead of testing the provider in isolation and hoping<\/em> clients agree, the consumer declares what it needs, and the provider proves it still delivers.<\/p>\n

In consumer-driven<\/strong> contract testing, the consumer owns the contract. The provider’s job is to never break it without a conversation.<\/p>\n

<\/a> A minimal contract test <\/h2>\n

You don’t need a heavyweight framework to start. Here’s a contract expressed as a plain JSON schema that both sides can share. <\/p>\n

\n
{<\/span> <\/span>\"request\"<\/span>:<\/span> <\/span>{<\/span> <\/span>\"method\"<\/span>:<\/span> <\/span>\"GET\"<\/span>,<\/span> <\/span>\"path\"<\/span>:<\/span> <\/span>\"\/users\/42\"<\/span> <\/span>},<\/span> <\/span>\"response\"<\/span>:<\/span> <\/span>{<\/span> <\/span>\"status\"<\/span>:<\/span> <\/span>200<\/span>,<\/span> <\/span>\"body\"<\/span>:<\/span> <\/span>{<\/span> <\/span>\"type\"<\/span>:<\/span> <\/span>\"object\"<\/span>,<\/span> <\/span>\"required\"<\/span>:<\/span> <\/span>[<\/span>\"id\"<\/span>,<\/span> <\/span>\"username\"<\/span>,<\/span> <\/span>\"email\"<\/span>],<\/span> <\/span>\"properties\"<\/span>:<\/span> <\/span>{<\/span> <\/span>\"id\"<\/span>:<\/span> <\/span>{<\/span> <\/span>\"type\"<\/span>:<\/span> <\/span>\"integer\"<\/span> <\/span>},<\/span> <\/span>\"username\"<\/span>:<\/span> <\/span>{<\/span> <\/span>\"type\"<\/span>:<\/span> <\/span>\"string\"<\/span> <\/span>},<\/span> <\/span>\"email\"<\/span>:<\/span> <\/span>{<\/span> <\/span>\"type\"<\/span>:<\/span> <\/span>\"string\"<\/span>,<\/span> <\/span>\"format\"<\/span>:<\/span> <\/span>\"email\"<\/span> <\/span>}<\/span> <\/span>}<\/span> <\/span>}<\/span> <\/span>}<\/span> <\/span>}<\/span> <\/span><\/code><\/pre>\n
\n<\/p><\/div>\n<\/p><\/div>\n
The consumer verifies it can rely on these fields. The provider verifies its real output still satisfies them.<\/p>\n
  <\/a> Verifying on the provider side <\/h2>\n
Run the contract against the live provider response in CI using Ajv<\/a>, a fast JSON Schema validator: <\/p>\n
\n
import<\/span> Ajv<\/span> from<\/span> \"<\/span>ajv<\/span>\"<\/span>;<\/span> import<\/span> addFormats<\/span> from<\/span> \"<\/span>ajv-formats<\/span>\"<\/span>;<\/span> import<\/span> contract<\/span> from<\/span> \"<\/span>.\/contracts\/get-user.json<\/span>\"<\/span> assert<\/span> {<\/span> type<\/span>:<\/span> \"<\/span>json<\/span>\"<\/span> };<\/span> const<\/span> ajv<\/span> =<\/span> addFormats<\/span>(<\/span>new<\/span> Ajv<\/span>({<\/span> allErrors<\/span>:<\/span> true<\/span> }));<\/span> const<\/span> validate<\/span> =<\/span> ajv<\/span>.<\/span>compile<\/span>(<\/span>contract<\/span>.<\/span>response<\/span>.<\/span>body<\/span>);<\/span> test<\/span>(<\/span>\"<\/span>GET \/users\/:id honors the consumer contract<\/span>\"<\/span>,<\/span> async <\/span>()<\/span> =><\/span> {<\/span> const<\/span> res<\/span> =<\/span> await<\/span> fetch<\/span>(<\/span>\"<\/span>http:\/\/localhost:3000\/users\/42<\/span>\"<\/span>);<\/span> expect<\/span>(<\/span>res<\/span>.<\/span>status<\/span>).<\/span>toBe<\/span>(<\/span>contract<\/span>.<\/span>response<\/span>.<\/span>status<\/span>);<\/span> const<\/span> body<\/span> =<\/span> await<\/span> res<\/span>.<\/span>json<\/span>();<\/span> const<\/span> ok<\/span> =<\/span> validate<\/span>(<\/span>body<\/span>);<\/span> if <\/span>(<\/span>!<\/span>ok<\/span>)<\/span> console<\/span>.<\/span>error<\/span>(<\/span>validate<\/span>.<\/span>errors<\/span>);<\/span> expect<\/span>(<\/span>ok<\/span>).<\/span>toBe<\/span>(<\/span>true<\/span>);<\/span> });<\/span> <\/code><\/pre>\n
\n<\/p><\/div>\n<\/p><\/div>\n
Now rename username<\/code> back to user_name<\/code> on the provider and this test fails before<\/em> the change merges \u2014 not after a consumer pages you at 2 a.m.<\/p>\n
  <\/a> Why this beats a shared staging environment <\/h2>\n
The classic alternative is end-to-end tests against a shared environment. They’re slow, flaky, and only catch breakage after<\/em> both services deploy together. Contract tests run in milliseconds, in isolation, and pin down responsibility: if the contract test goes red, the provider broke it.<\/p>\n
Critically, contracts catch additive-but-breaking<\/strong> changes that loose typing hides \u2014 a field changing from integer<\/code> to string<\/code>, a required<\/code> field going optional, an enum dropping a value. Your provider’s own tests pass because the provider is internally consistent. The contract is the only thing watching the boundary.<\/p>\n
  <\/a> Make breaking changes a deliberate act <\/h2>\n
The real payoff is workflow. Commit contracts to a repo both teams can see. Wire provider verification into the provider’s pipeline. When a provider change violates a contract, CI fails and forces the question: do we version this, or coordinate the migration?<\/em> <\/p>\n
\n
# .github\/workflows\/contracts.yml<\/span> name<\/span>:<\/span> contract-tests<\/span> on<\/span>:<\/span> [<\/span>pull_request<\/span>]<\/span> jobs<\/span>:<\/span> verify<\/span>:<\/span> runs-on<\/span>:<\/span> ubuntu-latest<\/span> steps<\/span>:<\/span> -<\/span> uses<\/span>:<\/span> actions\/checkout@v4<\/span> -<\/span> uses<\/span>:<\/span> actions\/setup-node@v4<\/span> with<\/span>:<\/span> {<\/span> node-version<\/span>:<\/span> 20<\/span> }<\/span> -<\/span> run<\/span>:<\/span> npm ci<\/span> -<\/span> run<\/span>:<\/span> npm run start:provider &<\/span> -<\/span> run<\/span>:<\/span> npx wait-on http:\/\/localhost:3000\/health<\/span> -<\/span> run<\/span>:<\/span> npm test -- contracts\/<\/span> <\/code><\/pre>\n
\n<\/p><\/div>\n<\/p><\/div>\n
Breaking the contract becomes a conscious decision with a paper trail, not an accident.<\/p>\n
  <\/a> Getting started without the ceremony <\/h2>\n
You can adopt this incrementally: start with your two or three most depended-on endpoints, write a schema for each, and fail the build when reality drifts. Add more as confidence grows. Tools like Pact add a broker and versioning once you outgrow plain schemas \u2014 but the principle is the same at every scale.<\/p>\n
If you’d rather not hand-roll the schemas and CI glue, APIKumo<\/a> lets you capture request\/response shapes from your existing collections, keep them versioned alongside live docs, and run them as checks \u2014 so the contract stays in lockstep with the API your consumers actually call. Whichever route you take, the goal is the same: catch the break before your users do.<\/p>\n<\/p><\/div>\n<\/div>\n<\/div>\n<\/div>\n
Fuente: Art\u00edculo original<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"
Ever shipped a backend change that passed every test, only to wake up to a frontend on fire? The API still returned 200 OK \u2014 it just renamed user_name to username, and three consumers broke silently. Unit tests didn’t catch it. Integration tests didn’t catch it. This is exactly the gap contract testing fills. What […]<\/p>\n","protected":false},"author":1,"featured_media":2648,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":"","jetpack_publicize_message":"","jetpack_publicize_feature_enabled":true,"jetpack_social_post_already_shared":true,"jetpack_social_options":{"image_generator_settings":{"template":"highway","default_image_id":0,"font":"","enabled":false},"version":2}},"categories":[41],"tags":[],"class_list":["post-2772","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-devto"],"jetpack_publicize_connections":[],"_links":{"self":[{"href":"https:\/\/tucumandevelopers.com\/index.php\/wp-json\/wp\/v2\/posts\/2772","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/tucumandevelopers.com\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/tucumandevelopers.com\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/tucumandevelopers.com\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/tucumandevelopers.com\/index.php\/wp-json\/wp\/v2\/comments?post=2772"}],"version-history":[{"count":0,"href":"https:\/\/tucumandevelopers.com\/index.php\/wp-json\/wp\/v2\/posts\/2772\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/tucumandevelopers.com\/index.php\/wp-json\/wp\/v2\/media\/2648"}],"wp:attachment":[{"href":"https:\/\/tucumandevelopers.com\/index.php\/wp-json\/wp\/v2\/media?parent=2772"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/tucumandevelopers.com\/index.php\/wp-json\/wp\/v2\/categories?post=2772"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/tucumandevelopers.com\/index.php\/wp-json\/wp\/v2\/tags?post=2772"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}