API lifecycle, explained
Most API programs describe the lifecycle in five broadly similar stages, whatever names they give them:
- Design: define the contract, often as an OpenAPI document, and review it with consumers.
- Build and test: implement against the contract with API testing and mocks.
- Release: publish documentation, SDKs and changelogs.
- Operate and evolve: monitor usage, ship backward-compatible additions, and version when breaking changes are unavoidable.
- Deprecate and retire: announce deprecation, send
Sunsetheaders, migrate consumers, then remove.
The longest and most expensive stage is evolution. An API typically lives for years after its first release, and every change made during that time has to be checked against consumers who were built for an earlier state of the contract.
Treating the lifecycle explicitly, with owners, review gates and a written deprecation policy, is what lets teams change APIs often without surprising the people who depend on them. See the API migration guide for the consumer side of the same lifecycle.
Related terms
- API versioning: API versioning is the practice of exposing multiple versions of an API at once so providers can ship breaking changes while existing clients keep using the version they were built for.
- API deprecation: API deprecation is the formal announcement that an endpoint, field or version is going away, with a timeline for clients to migrate before it is removed.
- API-first: API-first is a development approach where the API contract is designed and agreed before implementation, and treated as a product in its own right.