The API is not an afterthought
In the early years of web development, APIs were designed after the UI. You built the screens, then you wired up the data. The API was a byproduct of the implementation, shaped by the convenience of whatever the frontend happened to need at the time.
This approach has a predictable failure mode: APIs that are coupled to specific UI views, that change shape whenever a screen changes, and that are impossible to reuse without significant refactoring. In a world where your product might be consumed by a web app, a mobile app, a partner integration, and a public API simultaneously, this is not sustainable.
Design the contract first
API-first means writing the API specification before writing any implementation code. We use OpenAPI for REST and schema-first SDL for GraphQL. The specification becomes the contract between frontend and backend teams — and between your product and the outside world.
This approach surfaces design problems early. Naming inconsistencies, missing endpoints, ambiguous response shapes — these are cheap to fix in a YAML file and expensive to fix once two teams have built against an interface.
Versioning from day one
Versioning is one of those things that feels unnecessary until you need it. By the time you need it, it is too late to add cleanly. We include versioning in every API we build, even internal ones — if only because "internal" APIs have a way of becoming external ones.
We default to URL versioning for REST (/v1/, /v2/) and schema versioning for GraphQL. The overhead is minimal. The optionality it preserves is significant.
Documentation as a first-class deliverable
An API without documentation is not finished. We treat API documentation as a first-class deliverable, generated automatically from the OpenAPI spec and deployed alongside the API itself. When the spec changes, the docs update automatically.
We also include a set of runnable examples — Postman collections or Bruno files — in every API repository. The best documentation is something you can run and see working.
The payoff
The compounding benefit of API-first design is that every subsequent integration is easier. Adding a mobile app to a web product is trivial when the API was designed as a product in its own right. Partner integrations, webhooks, public developer programs — these all become possible without a rewrite.
The short-term cost is a few extra hours of design work at the start of a project. The long-term payoff is an API that can evolve without breaking clients, be consumed by teams you have not met yet, and serve as the foundation for a product that grows in ways you did not anticipate.