API Contract

Origin & evolution

The idea that an interface is a promise predates web APIs; it runs back through Bertrand Meyer's design-by-contract and the general principle of programming to an interface. What changed in the web era was making that promise a shared, machine-readable document, something a paragraph in a wiki could never be.

Swagger), created by Tony Tam in 2011 at Wordnik, gave teams a standard format for describing a REST API: paths, parameters, schemas, all in one file a machine could read. It spread far enough that in 2015 SmartBear donated the specification to a new OpenAPI Initiative under the Linux Foundation, and on 1 January 2016 the format was renamed OpenAPI. That governance move matters: the contract format became a neutral standard no single vendor controlled, which is what a contract between independent parties needs🫀NeedUserA user need, pain, desire, or constraintView reference →.

OpenAPI enabled a working style usually called design-first or contract-first: write the contract, agree it, then let producer and consumer build against it simultaneously, with mocks generated straight from the spec. A complementary idea attacked the problem from the consumer's side. Consumer-driven contracts, a pattern from Ian Robinson and J. B. Rainsberger, flip the direction: each consumer states exactly what it needs from the producer, and those expectations become tests the producer must keep passing. The Pact framework, in wide use since 2013, made this practical, recording consumer expectations and replaying them against the producer in its own pipeline. The two approaches answer different questions. OpenAPI describes the full surface the producer publishes; Pact verifies the specific slice each consumer actually relies on. Mature teams run both.

How it works in practice

A retailer is splitting checkout from inventory into two services owned by two teams. Before either writes logic, they agree an OpenAPI document for the inventory API: a GET /stock/{sku} endpoint returning a quantity and a reserved count, with a 404 shape for unknown SKUs. From that single file, the checkout team generates a mock server and builds against it; the inventory team generates request and response validators and builds the real thing behind it. Three weeks of parallel work, no blocking. When inventory later wants to rename a field, the contract turns a silent break into a visible one: the change fails the consumer-driven contract test that checkout published, so it is caught in the inventory pipeline, days before it could reach production. The contract did its job🔨JobUserJob To Be Done: what the user is trying to accomplishView reference → by making an incompatible change loud.

API contract vs. its neighbours

• API endpoint🔌API EndpointEngineeringA specific API endpointView reference → is a single operation: one path and method, like POST /orders. The contract is the whole agreement that contains many endpoints, plus the shared types, auth, and versioning rules that span them. The endpoint is a clause; the contract is the document.
• Service is the running software that honours the contract. One service exposes one or more contracts; the contract is the promise, the service is the thing kept to it. Swapping the service's internals must not change the contract.
• Bounded context🔲Bounded ContextEngineeringA DDD bounded context defining a service boundaryView reference → publishes a contract as the formal edge of its domain. Inside the context the model is rich and private; the contract is the deliberately narrower surface other contexts are allowed to depend on.

In the graph

In the Unified Product Graph, an API contract is the published interface node of the engineering region, the seam where one part of a system commits to another. A service⚙️ServiceEngineeringA deployable service or microserviceView reference → connects through service_exposes_api_contractServiceexposesAPI Contracthierarchy, and the contract's internal structure is held by api_contract_contains_api_endpointAPI ContractcontainsAPI Endpointhierarchy. Its role as a domain boundary appears in bounded_context_publishes_api_contractBounded ContextpublishesAPI Contracthierarchy, its documentation surface in developer_portal_documents_api_contractDeveloper PortaldocumentsAPI Contractcross-domain, and the reasoning behind its shape in api_contract_records_decisionAPI ContractrecordsDecisioncross-domain, which ties an interface choice back to the decision⚖️DecisionStrategyA recorded decision with context, rationale, and consequencesView reference → that set it. Modelling the contract as its own node, distinct from both the service behind it and the endpoints within it, captures the one property that makes contracts useful: they are the stable layer that lets producer and consumer change independently, and the graph can show exactly who depends on each one.