API-first, explained
In an API-first team, the first deliverable for a new capability is the contract: usually an OpenAPI or GraphQL schema reviewed by the people who will consume it. Only once the contract is agreed do backend, front-end and partner teams start building, often in parallel against mocks generated from it.
This differs from code-first, where the API is whatever the implementation happens to expose and the spec is generated afterwards. Code-first is faster at the start but tends to leak internal models into the public contract, which makes later changes riskier.
- Consistent design across teams, enforced with style guides and linting.
- Parallel development and earlier feedback from consumers.
- Docs, SDKs and tests generated from one source of truth.
API-first does not make an API immune to breaking changes. The implementation can still drift from the agreed contract, so teams pair it with contract testing and behavioral checks. See API design best practices.
Related terms
- OpenAPI Specification: The OpenAPI Specification is a standard, language-agnostic format (YAML or JSON) for describing HTTP APIs: their paths, operations, parameters, schemas and authentication.
- API lifecycle: The API lifecycle is the sequence of stages an API passes through, from design and build to release, versioning, deprecation and eventual retirement.
- API mocking: API mocking replaces a real API with a simulated one that returns predefined responses, so teams can build and test clients without the real service.
- Contract testing: Contract testing verifies that an API provider and its consumers agree on the requests and responses they exchange, so either side can change without silently breaking the other.