There's a pattern I've noticed across teams that ship fast with low defect rates: they write the API spec before writing any implementation code.
It sounds like adding work. In practice, it removes work — specifically the expensive, late-stage work of discovering misalignments between what the backend built and what the frontend expected.
The spec-first workflow
Backend and frontend engineers agree on the API contract together. This takes a meeting, not a week.
The contract is written as an OpenAPI YAML file and committed to the repo.
Frontend engineers import the spec into a mock server and start building against live endpoints immediately.
Backend engineers implement against the same spec. Their implementation is done when it matches the contract, not when the frontend works.
Integration is mechanical — the frontend just needs to change the base URL.
The key insight: the hard conversation ("what fields does this response need?", "what's the error shape?") happens at the start, in a meeting, when it's cheap to change. Not three weeks later when both sides have built assumptions into their code.
Why mock servers make spec-first work
Without a mock server, spec-first breaks down because the frontend can't build until the backend is done. The spec is just documentation — not a runnable contract.
With a mock server like moqapi.dev, the spec becomes a live API the moment it's written. Frontend development starts in parallel with backend development. The spec is the synchronization point.
What the spec also gives you
Auto-generated documentation (Swagger UI, Redoc)
Contract tests that verify the implementation matches the spec
Client SDK generation (OpenAPI Generator)
Postman collection generation
Mock servers (as above)
One artifact. Many uses. Write it first.
Top comments (1)
Well, sure, it's good practice to think early about the API and if possible discuss it with the customers before implementation. But designing a good API is hard - much harder than designing an implementation, because the implementation can be refactored, while the API is supposed to remain stable. Early choices must be made about what is hardcoded and what is controllable by API parameters - and the shape of those parameters matters much; so often an exploration phase (did I say 'agile' ?) helps to get it right - it cannot be written in marble from the start.