API-First Web Development, Explained Without the Buzzwords

API-first means you design the contract — what data exists, what shape it comes in, what operations are allowed — before building anything that consumes it. The website, the mobile app, and the internal dashboard then become clients of the same interface rather than three systems with three copies of the logic.

Why it matters commercially

The expensive version of a website is the one where business logic lives inside page templates. Add a mobile app two years later and you rebuild it. Add a partner integration and you rebuild it again. With a defined API, each new surface is a client, not a rewrite. That is the difference between a site that grows and one that gets replaced — the calculation behind the true cost of a custom website.

Design the contract before the database

Write the endpoints or the schema first, review it with whoever will consume it, then implement. Doing it the other way round leaks your table structure into your public interface, and you are stuck with it — because clients depend on shapes, not on your intentions.

Rules that keep an API pleasant

• Name resources as nouns, use HTTP verbs for actions: GET /projects, POST /projects.
• Be consistent about case and shape. Pick snake_case or camelCase and never mix.
• Return real status codes. A 200 containing {"error": true} breaks every client's error handling.
• Paginate from day one. Every collection grows, and retrofitting pagination is a breaking change.
• Version at the edge — /v1/ — before you need it, not after.
• Make errors machine-readable: a stable code, a human message, and which field failed.

REST or GraphQL?

REST for most business systems: cacheable, simple to debug, and every developer already knows it. GraphQL when many different clients need different slices of a deeply related dataset and over-fetching is a genuine cost. Choosing GraphQL for a five-endpoint marketing site adds a schema layer, a caching problem, and a learning curve in exchange for nothing.

Security is part of the design

Validate every input server-side regardless of what the client validates. Authorise per resource, not just per endpoint — the classic breach is a valid token reading somebody else's record. Rate limit anything public, never trust an ID from a URL, and keep the error messages unhelpful to attackers while remaining useful to clients. Same defensive posture as WordPress security, different stack.

When it is over-engineering

A brochure site with a contact form does not need an API layer; it needs a form handler. If there is exactly one client, no integration on the roadmap, and content that changes rarely, the extra indirection costs time and buys optionality you will not use. The relevant question is whether a second consumer is plausible within two years.

Where the CMS fits

API-first is the reasoning behind headless content management: content becomes data with an endpoint rather than pages tied to a theme. That has real benefits and real costs, laid out in headless vs traditional CMS, and it interacts with how much of your site is pre-built — see static vs dynamic.

Document it or it does not exist

An OpenAPI schema, example requests, and stated error codes turn a working API into a usable one. If a new developer needs a call with you to make their first request, the documentation is the missing feature.

Planning something that needs to feed more than one front end? Let's design the contract first — see recent work for examples.