Stop 08 · API TestingTopics · 7/9

API Contract Testing

In short

The mobile app expects a field called name. The backend renames it to fullName. Both teams' tests pass, and the app breaks in production. Contract tests catch exactly this.

Verifying that an API's actual behavior matches its documented contract (like an OpenAPI spec) — catching breaking changes before they reach consumers who depend on the documented interface.

The purple blob lines up a chunky plug with a matching wall socket.

Think of it like this

The plug and the socket

A three-pin plug fits a three-pin socket. Nobody checks the wiring every time, they trust the shape. Change one pin and nothing fits. An API contract is that agreed shape, and contract tests check both sides still match.

Watch it happen

A breaking change, caught early

Mobile app

Contract

User API

needs id, name

1/5The consumer, here the mobile app, writes down the fields it relies on.

The big ideas

What you need to know

The contract

Often an OpenAPI spec or a JSON Schema: field names, types, required fields and status codes.

Consumer-driven

Tools like Pact let each consumer record what it uses, and the provider verifies all of them.

Shape, not values

Contract tests check structure and types. Functional tests check business logic.

Run in CI

Contract checks run on every provider change, so breaking changes never reach users.

See it in code

Walk through the code

python

1import requests2from jsonschema import validate3 4POST_SCHEMA = {5    "type": "object",6    "required": ["id", "userId", "title", "body"],7    "properties": {8        "id": {"type": "integer"},9        "userId": {"type": "integer"},10        "title": {"type": "string"},11        "body": {"type": "string"},12    },13}14 15r = requests.get("https://jsonplaceholder.typicode.com/posts/1", timeout=10)16validate(instance=r.json(), schema=POST_SCHEMA)  # raises if the shape is wrong

1/3The schema lists fields that must always be present.

A lightweight contract check with JSON Schema. Install with pip install requests jsonschema.

Save yourself the pain

Common mistakes

Oops

Treating contract tests as a replacement for functional tests.

Do this instead

Contracts check shape. You still need tests that the values and rules are correct.

Oops

Writing the schema once and never updating it with the API.

Do this instead

Keep the contract in Git next to the code and review changes to it like code.

Your mission

Break a contract on purpose

~25 min

Quick check

What does a contract test mainly protect against?

Go deeper

1Compare a sample API's actual response against its documented schema for discrepancies.
2Learn why contract testing matters especially for microservices with many API consumers.
3Explore a contract testing tool's basic concept (like Pact) at a high level.