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.
In brief
- A mock lets you write and test code before the client's API is ready, but it won't tell you when the client changes that API.
- Contract tests share one description file: you test your side against the mock, then send every request in that file to the real API to check it.
- Don't over-mock: critical flows must still run against the real API, and the contract has to be updated every time the API changes.
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:
{
"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:
# 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()
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:
# 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
# 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.
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.
# 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)
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.
Was this article useful?
Thanks for the feedback!