# When a client renames one field, your integration fails silently

> An afternoon with a mock server and a contract test in plain Python catches the change before the weekend revenue report reads zero.

Original: https://fdetimes.net/en/guides/mock-client-api-contract-testing/

Picture this: on Monday you deploy an integration with a client's order system and every test is green. On Thursday, the client's backend team renames the field `total` to `amount` without telling anyone. Your code doesn't crash. It quietly returns `None`, and the weekend revenue report comes out at zero.

No complicated bug is needed for this to happen. All it takes is two teams working on one integration point with nothing to hold either side to what they agreed. For a forward deployed engineer the risk is worse, because the API usually sits on the client's side. You probably don't control their release schedule, and you may not even be able to read their code.

This guide covers two jobs in one afternoon. First, mock the client's API so you can start work straight away. Second, write contract tests so you find out as soon as the client changes that API.

## What will you build?

You will end up with four Python files: a contract file, a mock server, a test for your side, and a verify script that runs against the real API. You need Python 3, a terminal and, ideally, the staging URL of a real API to try the final step.

The code below is a **simplified, hand-rolled version** that uses only Python's standard library, so the mechanics are easy to see. On a real project, Pact does this work for you.

According to Pact's documentation, it is a "code-first" tool for contract testing both HTTP and message integrations, aimed mainly at developers and testers who write code. Look up Pact's actual syntax at docs.pact.io; here the mechanism is rebuilt by hand so you can see how it works.

## Step 1: Write down the agreement before writing code

Pact works like this: tests on the consumer side (the side calling the API, which is you) generate a pact file describing each interaction. Here you write that file by hand, using a hypothetical client orders API as the example:

```json
{
  "consumer": "fde-integration",
  "provider": "customer-orders-api",
  "interactions": [
    {
      "description": "get an existing order",
      "request": {"method": "GET", "path": "/orders/42"},
      "response": {"status": 200,
                   "body": {"id": 42, "status": "PAID", "total": 150000}}
    },
    {
      "description": "order does not exist",
      "request": {"method": "GET", "path": "/orders/999"},
      "response": {"status": 404, "body": {"error": "not_found"}}
    }
  ]
}
```

(The two descriptions read "fetch an existing order" and "order does not exist".)

Save it as `contract.json`. **Check:** give this file to an engineer on the client's side. If they confirm the API returns exactly this, you have your first written agreement, and any place where the two sides understand things differently will surface right here.

The 404 case is there on purpose. Mocks let you test beyond the usual scenarios, and error cases are where integration code breaks easily and where few people bother to test.

## Step 2: Build the mock from the contract itself

A mock API is a web service that imitates the real one, and you can use it from the very start, before the real service is ready. This mock reads straight from the contract, so the two never drift apart:

```python
# mock_server.py — simplified version, matches on path only
import json
from http.server import BaseHTTPRequestHandler, HTTPServer

CONTRACT = json.load(open("contract.json"))

class Mock(BaseHTTPRequestHandler):
    def do_GET(self):
        for it in CONTRACT["interactions"]:
            if it["request"]["path"] == self.path:
                res = it["response"]
                self.send_response(res["status"])
                self.send_header("Content-Type", "application/json")
                self.end_headers()
                self.wfile.write(json.dumps(res["body"]).encode())
                return
        self.send_response(500)
        self.end_headers()

HTTPServer(("localhost", 8001), Mock).serve_forever()
```

```bash
python3 mock_server.py &
curl -i http://localhost:8001/orders/999
```

**Check:** you should see `HTTP/1.0 404` and the body `{"error": "not_found"}`. Calling a path that isn't in the contract returns 500. That error is deliberate: your code is calling something that isn't in the agreement.

## Step 3: Test your code against the mock

Here is the actual integration code, with its test:

```python
# client.py
import json, urllib.request, urllib.error

def get_order_total(base_url, order_id):
    try:
        with urllib.request.urlopen(f"{base_url}/orders/{order_id}") as r:
            return json.load(r).get("total")
    except urllib.error.HTTPError as e:
        if e.code == 404:
            return None
        raise
```

```python
# test_consumer.py
from client import get_order_total
BASE = "http://localhost:8001"
assert get_order_total(BASE, 42) == 150000
assert get_order_total(BASE, 999) is None
print("consumer OK")
```

**Check:** `python3 test_consumer.py` prints `consumer OK`. Note the line `.get("total")`: when the field disappears, the function doesn't raise an error, it returns `None`. That is exactly the silent failure from the opening, and a great deal of integration code is written just like this.

A mock is an isolated API, unaffected by changes to services, databases or external systems. That is why this test runs even when the client's staging environment is down.

But that same isolation is the weakness. If the client renames `total` to `amount`, the mock still returns `total` and the test stays green. A mock helps you while the client isn't ready. It won't tell you when the client has changed the API.

**Key point:** A mock lets you work while the client isn't ready; a contract tells you when the client has changed something.

## Step 4: Take the contract to the real API

This is the other half, and the reason the contract exists. Pact calls this step provider verification: each request in the pact is sent to the provider. Contract testing checks an integration point by testing each application on its own. You test your side against the mock; the client's side is tested with the same file.

```python
# verify_provider.py — simplified: compares status and field names, not values
import json, sys, urllib.request, urllib.error

contract = json.load(open("contract.json"))
base = sys.argv[1]
fails = 0
for it in contract["interactions"]:
    req, exp = it["request"], it["response"]
    try:
        r = urllib.request.urlopen(base + req["path"])
        status, body = r.status, json.load(r)
    except urllib.error.HTTPError as e:
        status, body = e.code, json.load(e)
    missing = [k for k in exp["body"] if k not in body]
    if status != exp["status"] or missing:
        fails += 1
        print(f"FAIL {it['description']}: status={status}, missing {missing}")
sys.exit(1 if fails else 0)
```

```bash
python3 verify_provider.py https://staging.customer.example
```

The script deliberately compares field names, not values, because order 42 on the client's staging environment will certainly not have a total of exactly 150000. **Check:** when the client renames a field, you will see `FAIL get an existing order: status=200, missing ['total']` ("thiếu" means "missing") and exit code 1.

Contract tests make debugging much faster, and the reason is right there in that output: the error names the exact field and the exact interaction, instead of a mysterious zero on a dashboard.

Note one hidden assumption: order 42 must exist on staging. Agree fixed test data with the client, or the verify step will fail for reasons that have nothing to do with the contract.

## Step 5: Put it in CI so nobody has to remember to run it

A script that someone has to remember to run will sooner or later be forgotten. Schedule `verify_provider.py` in CI. Because the script returns a non-zero exit code on failure, the pipeline turns red on its own.

With Pact, Pact Broker handles the CI wiring. When the number of APIs and teams that need verifying starts to grow, that is the time to drop the hand-rolled version and move to this tool.

## Three common mistakes

The first is over-mocking. The rule is to avoid over-mocking and use the real API whenever possible, especially for critical flows. If the client's payment flow has only ever run against a mock, you haven't really tested it.

The second is leaving the contract untouched. Tests only reflect the system accurately if they are updated as the API changes. When the client announces an API change, the first thing to edit is `contract.json`, not the code. The mock and the verify step follow automatically.

The third is matching too strictly. If you assert every value against real data, the test will fail every day and the team will learn to ignore it.

## How does this skill apply on site with a client?

In your first week with a client, the API is often unfinished and the documentation out of date. Writing `contract.json` and taking it to the client's engineers is the fastest way to expose where the two sides understand things differently, before a single line of code is written.

Once the integration is in production, a nightly verify run is what tells you the client has just changed the API, rather than waiting for them to call.

On your CV, don't just write "knows Pact". State how many interactions you built contracts for and which kinds of change you caught before they reached production.

Your integration code only works correctly as long as the client's API stays as both sides agreed. Contract tests are how you check that every day.

**Try this week:**

- Pick an external API your project calls and write a contract.json for 2 interactions: one success case and one error case.
- Run verify_provider.py against that API's staging environment and add it to CI to run daily.
- Add a specific line to your CV: how many interactions you built contract tests for, and which kinds of error you caught before production.

## Sources

- [What is API mocking?](https://blog.postman.com/what-is-api-mocking/)

- [What is API Mocking? Definition, Guide, and Best Practices](https://katalon.com/resources-center/blog/what-is-api-mocking)

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

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

- [A Complete Guide to API Contract Testing](https://testsigma.com/blog/api-contract-testing/)

- [How to run API integration tests](https://www.merge.dev/blog/api-integration-testing)
