Contracted design
A boundary without a contract is a boundary defined by whatever the caller happened to try. Contracted design means each interface states its promise explicitly, in a form a machine can check.
What counts as a contract
Section titled “What counts as a contract”Not only REST. Anything that crosses a boundary can carry one:
- Synchronous interfaces — OpenAPI, GraphQL SDL, WSDL.
- Asynchronous messages — AsyncAPI, and the schema of every event on the event landscape.
- Structural rules — which module may depend on which, expressed so the build can fail when it is broken.
Explicit, and enforced
Section titled “Explicit, and enforced”The distinction that matters is between a documented promise and an enforced one. A contract earns the name when breaking it breaks something:
- it is validated on submission, not on inspection;
- it is versioned, so a breaking change is visible as one;
- it is graded, so “technically valid” and “fit to depend on” are different verdicts.
api-hub scores contracts along four dimensions — foundational compliance, security, developer experience and mock readiness — precisely because a document can parse cleanly and still be unusable by the next team.
Consequence
Section titled “Consequence”Once a boundary is contracted, the thing behind it becomes free to change. That is the payoff, and the reason this principle underwrites sustainable design.