API-First Design - advantages, disadvantages.
Why teams flip from Code-First to API-First - and where the paradigm bites back.
stack · openapi · contract-first · mock servers · cdc
abstract
Systematic literature review combined with five qualitative expert interviews. Treats the OpenAPI spec as the single source of truth and examines how that changes developer experience, scalability, and team coordination.
key findings
- Strengthens loose coupling for microservices - contracts enforce decoupling Conway's Law usually fights against.
- Parallel work: frontend, backend and QA build against mock servers as soon as the contract is signed.
- Auto-generated docs stay in sync with the spec - kills documentation drift.
- Higher upfront cost; spec-first isn't a substitute for interpersonal communication.
so what
Not a silver bullet. Strict API-First for external/partner APIs; lighter Consumer-Driven Contracts for internal teams; Code-First for prototyping with a planned "flip" once the project stabilizes.