The API is a product. The contract is the architecture. The federation is the unit of trust. The operating model is what keeps the API ecosystem honest as the underlying systems change.
§ 01 ·
An API ecosystem is the set of APIs an organisation publishes and consumes, plus the contracts that govern them, plus the operating model that keeps them current. The ecosystem is not a list of endpoints; it is a federation of systems that exchange data and behaviour across explicit contracts. The contracts are the architecture; the endpoints are the implementation.
The discipline that has held up is API-as-a-product. An API has four roles.
The product has a name, a changelog, a status page, and a feedback channel. The producer is responsible for the contract; the consumer is responsible for the implementation.
Two failure modes recur.
The right governance scope is the actual consumer surface, not a hypothetical one.
§ 02 ·
The architectural primitives that have held up across the API ecosystems we work with.
The schema, the SLA, the deprecation policy, the rate limits, the authentication requirements, the error model: every one of these is part of the contract. The contract is documented, versioned, and testable. The implementation is the producer's problem; the contract is the consumer's guarantee.
The schema is a machine-readable artifact (OpenAPI, Protobuf, JSON Schema, GraphQL SDL). The documentation is generated from the schema, not maintained by hand. The tests are generated from the schema, not maintained by hand. A contract that is maintained by hand is a contract that drifts from the implementation.
Two APIs exchanging data is not federation; it is a copy of data with extra steps. Federation requires a contract: schema, conformance tests, failure modes, deprecation policy. Without the contract, the integration is just a less honest one.
The API has a roadmap, a changelog, a status page, a feedback channel, a deprecation policy. The producer is responsible for the contract; the consumer is responsible for the implementation. The contract is reviewed; the implementation is owned.
The API returns errors that are machine-readable and human-actionable. The error response includes an error code (machine-readable), a human-readable message, and ideally a link to the documentation. The error model is documented; the error responses are tested.
§ 03 ·
§ 04 ·
Fit the style to the consumer surface.
The style is the tool; the contract is the architecture.
With explicit, machine-readable versioning. The version is in the URL (path or query), in the header, or in the content type. The version is documented; the version is tested; the version is deprecated with a documented timeline. A breaking change triggers a new version. An additive change is not a breaking change. The contract is the version.
With a documented deprecation policy, executed in public.
A deprecation that is not enforced is a deprecation that is not real.
With workload identity, short-lived tokens, and mTLS. Each service has a workload identity (SPIFFE, a Kubernetes service account, a cloud-native workload identity). The service authenticates itself with its workload identity. The token is short-lived (minutes, not hours). The communication is mTLS (mutual TLS, both sides authenticated). The pattern holds at any scale: identity, short-lived credentials, mTLS, per-request authorisation.
With three layers.
All three are required. A system with only contract tests has tested the schema, not the system. A system with only end-to-end tests has tested the system, not the contract.
§ 05 ·
A contract documented by hand is a contract that drifts from the implementation. The schema is a machine-readable artifact. The documentation is generated from the schema. The tests are generated from the schema. The consumer's code is generated from the schema. Each is a tool the producer uses to keep the contract honest.
An API treated as an implementation detail of one team is an API that other teams consume by accident, building dependencies on a contract that is not really a contract. The producer is not responsible for the contract; the consumer is not responsible for the implementation. The result is an implicit dependency on an explicit implementation, the worst of both worlds.
An API that uses REST for everything has not been designed. The style fits the consumer surface.
The style is the tool; the contract is the architecture.
An API that returns 500 with a stack trace has not been designed. The error response is part of the contract. The error response includes a machine-readable error code, a human-readable message, and ideally a link to the documentation. The error model is documented; the error responses are tested.
An API with no deprecation policy is an API that cannot be changed. The deprecation policy is documented. The deprecation is announced. The deprecation is timed. The deprecation is enforced. A deprecation that is not enforced is a deprecation that is not real.
§ 06 ·
Public frameworks and writing that inform our practice.
The most useful recent treatment of API design. The book is organised by the problems the API designer faces (resource modelling, error handling, versioning, and others) and the patterns that solve them. The treatment of the API as a product is the contribution that has held up.
The API-as-a-product framing. Masse was one of the first to argue that the API is the product, not the implementation. The book is older but the framing is still the right one.
The book that made distributed systems a discipline. The treatment of consistency, fault tolerance, and replication is the most rigorous available. The book is not about APIs specifically, but every API design problem in a distributed system is a problem the book addresses.
The contract format. The most useful of the API specification formats because it is mature, tooled, and human-readable. The schema is the contract; the documentation is generated from the schema; the tests are generated from the schema.
The service-to-service counterpart to BeyondCorp. Same per-request discipline, different trust boundaries (workload identity, not user identity). The model generalises to any environment where one workload calls another, which is most modern architectures.
Weighing an API governance initiative, evaluating a contract pattern, or trying to make an existing API ecosystem more than an implementation detail? Useful at the boundary between the contract and the implementation. A short conversation is the right next step.
Learn more