API Contract Testing Language

Consumer-driven contract testing is an approach where each consumer of an API defines the exact shape of the requests it sends and the responses it expects, publishing these as a "contract". The provider then verifies it can satisfy every consumer's contract before deploying, catching breaking changes without requiring consumers and providers to be tested together in a shared environment.

Pact is the most widely adopted consumer-driven contract testing framework. Engineers describe the workflow as: "the consumer writes an interaction", "the Pact file is published to the Pact Broker", "the provider verifies the pact", and "the can-i-deploy check gate is run in CI before any deployment proceeds".

A breaking change is any modification to an API that causes an existing consumer contract to fail — for example, removing a required field, renaming a property, or changing a response status code. Engineers classify changes as "backwards-compatible" (additive) or "breaking" (destructive), and use semantic versioning to signal the nature of the change to consumers.

The Pact Broker is a shared storage and verification hub for contract files. Teams talk about "publishing pacts to the broker", "tagging pacts with a branch or version", "fetching pacts for provider verification", and running the "can-i-deploy" CLI command to check whether all relevant contracts pass before a deployment is allowed to proceed.

In contract-first development, teams agree on and publish the API schema (typically as an OpenAPI specification) before writing any implementation code. This contrasts with test-first development, where tests are written before implementation but the API shape may still evolve. Contract-first provides a "shared source of truth" that both consumer and provider teams code against independently.

Common strategies and their associated vocabulary include "URI versioning" (/v1/, /v2/), "header versioning" (Accept: application/vnd.api+json;version=2), "query parameter versioning", and "sunset headers" to communicate deprecation timelines. Teams also discuss "maintaining backwards compatibility" and "deprecation notices" when retiring old API versions.

A stub is a simplified replacement for a dependency that returns predetermined responses without verifying how it was called. A mock is a more sophisticated test double that also verifies the interactions — asserting that specific methods were called with expected arguments. In contract testing, the Pact framework generates a "mock provider" that the consumer tests against to record the contract.

Contract testing is integrated by adding "publish pact" steps to consumer CI jobs and "verify pact" steps to provider CI jobs, both feeding results to the Pact Broker. The critical gate is the "can-i-deploy" check, which queries the broker to confirm that the version being deployed is compatible with all deployed consumer versions before the deployment proceeds.

Schema validation is the process of checking that request and response payloads conform to a declared schema — typically JSON Schema or an OpenAPI specification. Teams distinguish between "structural validation" (correct field types and required fields) and "semantic validation" (values within acceptable ranges or enumerations), using validators like Ajv or built-in OpenAPI tooling.

In microservices architectures, independent teams own separate services that must interoperate reliably. Mastering contract testing vocabulary allows engineers to participate in cross-team discussions about API compatibility, articulate the rationale for consumer-driven testing in architectural reviews, and write precise PR descriptions and test documentation that other teams can act on without ambiguity.