API Contract

An API contract is the promise one system makes to another about how they will talk: what can be asked, what will come back, and what happens when things go wrong. As software becomes assemblies of services rather than single programs, these contracts — not the software — are what hold enterprises together.

What It Is

An API contract (or API specification) is the documented agreement defining a system's programming interface: every endpoint (URL) that can be called, the operations available on each, the exact structure of requests and responses, error codes and their meanings, authentication requirements, and rate limits. Modern contracts are usually machine-readable — OpenAPI/Swagger being the dominant format — which allows code, documentation and tests to be generated directly from them. A contract is versioned: when the interface changes, the version changes, and consumers must be able to rely on old versions for a defined period.

Why It Matters to You

Every integration your organisation runs is governed by one of these, whether documented or improvised — and undocumented contracts are where integrations go to die silently. The contract is also your leverage in vendor negotiations: a system whose API is contractually specified with guaranteed availability and deprecation notice periods is integrable and replaceable; a system whose API is 'whatever the current code does' is a dependency trap. Executives signing SaaS agreements should ask two questions: where is the API contract, and what notice do we get before it changes? The answers determine your exit costs.

When You'll Meet It

Whenever systems are integrated or SaaS is procured. The contract document (or its absence) should be an explicit attachment to any agreement involving data exchange.