API Platform & Lifecycle · Contract-First Design
The Contract-First Workflow
Why teams write the spec before the code, and what the workflow looks like.
In contract-first (design-first) development, the API description — OpenAPI for HTTP, AsyncAPI for events, Protobuf for gRPC — is written and reviewed before implementation. Consumers review real request/response examples early, frontend and partner teams build against mock servers, code and SDKs are generated from the contract, and CI verifies the implementation still matches it. Code-first (generate the spec from annotations) is faster for small internal APIs but tends to leak implementation details and makes review harder.
Contract-first vs code-first
| Criterion | Contract-first | Code-first |
|---|---|---|
| Consumer feedback | Before coding | After implementation |
| Parallel frontend/backend work | Yes (mocks) | Limited |
| Spec quality | Deliberate, reviewed | Mirrors implementation details |
| Speed for tiny internal APIs | Slower start | Faster |
| Drift risk | Needs CI checks | Low (generated), but design is accidental |
# Typical pipeline
1. Author/update openapi.yaml in a PR (design review with consumers)
2. CI: spectral lint → oasdiff breaking-change check → publish preview docs + mock server
3. Generate server stubs / types and client SDKs
4. Implement; CI validates responses against the spec (contract tests)
5. Merge → publish docs, SDKs and changelog
Common pitfalls
- Spec written once and never updated (drift).
- Design reviews that only check naming.
- Generated code that developers then edit by hand.
Key points
- Spec before code, reviewed with consumers
- Mocks enable parallel work
- CI keeps code and spec in sync
Further reading: OpenAPI best practices
Practice questions
What's the main benefit of contract-first for frontend teams?
Answer
They can build against a mock server generated from the agreed spec while the backend is implemented, and give feedback before the design is locked in code.
How do you prevent drift between implementation and spec?
Answer
Validate requests/responses against the spec in tests (contract tests), generate types/stubs from the spec, and run breaking-change checks in CI.
Open in the app to mark lessons complete, take notes and track your progress.