API contracts
An API contract specifies the data, meaning and observable behavior of an interface. It includes success and relevant error cases.
- InputWhat the caller has to deliver.
- ResultsSuccess and mistakes are distinguishable.
- OwnerA building block is responsible for the contract.
Context
Why this is important
Without a clear contract, callers guess what a call means and what errors look like. Then cooperation breaks down at the margins. How contracts change later is handled API versioning.
This building block explains the content of an interface contract. For changes to existing contracts, see API versioning.
At a glance · Contract between caller and provider
Filled contract stock reserve
Order reserved on the contract of the storage module two cups for B-1042. The reservation has a stable identifier and an expiration date.
This is how you read the picture
- Input Entry section: Order ID B-1042, product T-7, quantity 2.
- Results Sections Success (Reservation ID R-)77) and technical error (BEST_REICHT_NOT.
- Owner Owner section: Warehouse module; repeat section to the same order ID and location.
- Operation
- Stock Reserve
- Input
- Order ID B-1042, product T-7, quantity 2
- Success
- Reservation ID R-77, valid until 10:15
- Technical error
- EXISTENCE_REICHT_NOT with available quantity
- Retry
- The same order ID and position indicate the same reservation order
- Owner
- bearing module
Benefits & limitations
Helps if:
- A joint observable contract supports independent development of providers and consumers.
- Defined meaning, error formats and timing behaviour make a contract more informative than a field schema alone.
- Testable promises facilitate compatible changes while an interface grows across multiple releases.
Boundaries
- A schema alone does not define meaning or failure behaviour; without explicit guarantees, callers may interpret them differently.
- Silent meaning changes break callers despite unchanged data type and count as incompatible changes; see API versioning.
- The contract will only remain resilient as long as consumers review it; untested promises are assumptions.
In practice
- Describe operations, data meaning, failures, identity and timing behaviour from the consumer's perspective. Go beyond documenting internal field names.
- Check contract tests against producer and consumer and record compatibility when changes occur. HTTP methods and status codes retain their protocol semantics.
- Distinguish resource representations, the HTTP protocol and the business contract. API Versioning governs migration; Authentication & Authorisation governs access.
- Test semantic compatibility with examples. Agree the amount, currency and tax treatment of a discounted shopping cart. Use this example in contract tests so changes in business meaning are detected even when field names remain the same.
Read the detailed explanation
An API contract describes permitted operations, data meaning, error formats and observable behaviour. HTTP is a protocol with defined semantics for methods, status codes and headers. REST is an architectural style with additional constraints, including a uniform interface and statelessness. An HTTP API conforms to REST when it meets those constraints.
Providers and consumers evolve the contract together without exposing internal implementation. Schema and compatibility tests make structure and behaviour testable. Semantic changes can be incompatible even when field names and types remain unchanged.
API Versioning addresses compatibility across contract versions; Authentication & Authorisation establishes identity and access rights as separate security guarantees.
OpenAPI describes synchronous HTTP interfaces; AsyncAPI describes messaging contracts. With Consumer-Driven Contracts, for example using Pact, consumers express expectations as tests that the provider runs.
In the shop, an amount needs a clear meaning alongside its numeric format and currency: net or gross, before or after discounts. Providers and consumers can validate the same schema successfully yet produce different invoices. A business example makes the expected interpretation testable.
Check your understanding
Test yourself in three stages
ReadingCheck in the picture
What identifier does the warehouse return in the event of success, and how long does it last?
View the solution with justification
The reservation ID R-77, valid until 10:15. It refers to the specific confirmed reservation.
ApplyingTransferred to a new situation
The warehouse delivers BESTAND_REICHT_NOT with available quantity. What can ordering do with it?
View the solution with justification
It can handle the error case, for example adjust the quantity or reject it because the contract provides the available quantity.
EvaluateWeighing an alternative
Should the Treaty only describe success and leave mistakes open? How do you weigh up?
View the solution with justification
It will be shorter, but order must guess unclear exits. A contract with a described error such as BESTAND_REICHT_NOT makes every outcome treatable.
Explore further
These building blocks continue the thoughts of this page.
References
- OpenAPI Initiative · Specification (opens in new tab)Defines the machine-readable description of HTTP API contracts.
- AsyncAPI Initiative · Specification (opens in new tab)Describes messages, channels and contracts of event-based interfaces.
- Microsoft · Web API Design (opens in new tab)Covers resources, HTTP behavior, and versioning decisions.
- Gregor Hohpe, The Many Facets of Coupling (opens in new tab)Differentiates several dimensions of coupling, including time and semantic dependencies.