# Pact warns you before a client's API change breaks your integration

> The contract comes from your own tests, so the client can add fields freely and is blocked only when a change breaks the parts you actually use.

Original: https://fdetimes.net/en/tools/pact-contract-testing-client-api-changes/

In Pact, nobody sits down to write a contract by hand. The contract is generated when the API caller's automated tests run, and that is why the tool suits FDEs better than most other approaches to integration testing.

The situation will be familiar: your integration calls into a client's system, runs smoothly for weeks, then one morning breaks because the team on the other side renamed a field.

Nobody warned you, because they did not know your code used that field. Pact records exactly what your side relies on and puts that list into their CI, so the failure shows up before the deploy rather than after it.

## What does Pact actually check?

Pact's official documentation, maintained by the Pact Foundation, describes it as a code-first tool for testing HTTP and message integrations using contract tests. The two roles to understand are consumer and provider. Pact defines a consumer as an application that makes use of the functionality or data of another application to do its job.

On a client project, the consumer is usually you: the agent, data pipeline or integration service you built. The provider is the client's API. Because the contract comes from the consumer's tests, it contains only what the consumer really uses. Everything else, the provider is free to change.

**Key point:** The best contract records only what you actually use, and nothing more.

The idea predates Pact by some years. In 2006 Ian Robinson wrote "Consumer-Driven Contracts: A Service Evolution Pattern" on Martin Fowler's site, using the term consumer-driven contract for a provider contract shaped by what its consumers need. Pact turned that pattern into a working tool.

## An end-to-end example

Imagine you are building an integration with a retail client's order service. The endpoint that fetches an order returns 30 fields, but your code reads only 3: the order ID, the status and the total. That is the contract you need to protect.

First, you write a consumer test for exactly that request and declare an expected response containing only those 3 fields. The sketch below only illustrates what the scenario says; it does not follow the syntax of any Pact library:

```text
When the consumer sends:   GET /orders/123
The provider must return:  status 200
Body contains at least:    order_id, status, total
```

When the test runs, Pact starts a mock provider: it compares the actual request your code sends with the expected one, then returns the declared response. Your code handles that response as if it were real, and the test run produces a pact file.

The second step happens on the client's side. The pact file is used to verify the real provider: Pact replays each request in the file against their service and checks the response. According to Pact's documentation, verification passes if each response contains at least the data described in the contract.

Consider what happens when the client changes the API in two ways. They add a 31st field for a loyalty programme: verification still passes, because the 3 fields you need are still there. They rename the status field: verification fails straight away in their CI, before that version reaches production and before your integration breaks in the middle of the night.

## Three common mistakes in a first contract

The most common mistake is declaring all 30 fields simply because the API returns 30 fields. The contract then binds the client to 27 fields you never read, every harmless change on their side turns verification red, and before long the client's team treats the verify step as noise.

The rule is simple: open your code, and put a field in the contract only if some line actually reads it.

The second mistake is the opposite: writing the consumer test, generating the pact file and stopping there. The mock provider proves only that your code handles the response you described yourself. The real value arrives when the pact file is used to verify the real provider, so do not count the job as done until verification runs on the client's side.

The third mistake is writing only a "happy path" scenario. If your code also handles the case where an order is not found, that is a separate scenario the contract needs, because Pact protects only what you have written tests for.

## Blocking a deploy with an exit code

Pact files need somewhere to be stored and shared, and that is the job of the Pact Broker. The Broker knows the dependencies between applications, so the can-i-deploy command can answer a very specific question: is the version about to be deployed compatible with the versions of the other applications already running in the target environment?

The answer is an exit code: 0 means deploy, 1 means do not. That lets it plug straight into any pipeline without anyone having to read a report. If the client needs SSO, user management or a better interface, Pact's documentation describes PactFlow as a commercial fork of the Pact Broker.

## What Pact cannot replace

The first limit sits in Pact's own description of itself. The project's FAQ calls it "contract by examples", as opposed to a schema that describes every possible state. Pact protects only the scenarios you have written tests for; any field you forget to declare, it will not guard for you.

The second limit: the FAQ lists cases where Pact is a poor fit, including APIs with so many consumers that a direct relationship with each one cannot be maintained. A public API serving thousands of customers falls into this category. An internal client service where your integration is one of a handful of consumers is an excellent fit.

The third limit is about people, not technology. Pact is worth something only if the client's team agrees to run the verify step in their CI. The practical advice: do not open with "install Pact", but with a specific incident and a small contract already written for the exact endpoint that caused it.

## What to learn first

Start with the two roles, consumer and provider, because everything else revolves around them. Then write a consumer test for one HTTP endpoint using the Pact library for your project's language; Pact is built for many languages, pact-js for TypeScript among them, so you will rarely need to change stack.

Read the generated pact file carefully, and only then move on to the Broker and can-i-deploy. If your integration runs over a queue rather than HTTP, leave message pacts, available since the V3 specification, until you are comfortable with the HTTP flow.

On a CV, a line such as "brought contract tests into the client's CI, blocking API changes that would break the integration before deploy" says more than the word "Pact" in a skills list. When reading FDE job ads, phrases such as "integration with customer systems" or "integration reliability" are where this story belongs.

Integrations with clients rarely break because your code is wrong. They usually break because neither team knows what the other relies on, and a pact file is a way of writing that down so a machine can check it for you.

**Try this week:**

- Pick an integration that calls a client's API, list exactly the fields your code reads, and compare that with the number of fields the API returns.
- Write a Pact consumer test in your project's language for a single endpoint, then open the generated pact file and read it.
- Ask the client's team whether their CI could run one extra verify step, before formally proposing Pact.

## Sources

- [Pact Docs (docs.pact.io)](https://docs.pact.io/)

- [How Pact works](https://docs.pact.io/getting_started/how_pact_works)

- [Can I Deploy - Pact Docs](https://docs.pact.io/pact_broker/can_i_deploy)

- [Pact FAQ](https://docs.pact.io/faq)

- [Pact Foundation · GitHub](https://github.com/pact-foundation)

- [pact-foundation/pact-specification](https://github.com/pact-foundation/pact-specification)

- [Consumer-Driven Contracts: A Service Evolution Pattern](https://martinfowler.com/articles/consumerDrivenContracts.html)
