Designing REST APIs that outlive their frontend
Your API will outlast the UI that prompted it — probably by years. Design it for the second consumer you have not met yet.
By Shashi Kumar ·
Every API I have built has outlived the interface it was built for. Web app becomes web app plus mobile. Mobile becomes mobile plus a partner integration. The frontend gets rewritten; the API endures, accumulating consumers nobody planned for.
Design accordingly.
The mistake: modelling the screen
The most common API design error is one endpoint per screen. /dashboard-data. /settings-page. /checkout-step-2.
It feels efficient — one call, exactly the data the page needs, no waste. And it works perfectly right up until the second consumer arrives and needs the same data in a different shape. Now you have /dashboard-data-mobile, and six months later nobody can safely change either.
Model the domain, not the view. Resources that mean something to the business will still mean something when the UI is unrecognisable.
Six decisions that age well
Version from day one. /v1/ costs nothing now and saves an impossible migration later. Adding versioning after you have external consumers is a project; having it from the start is a prefix.
Never break a response shape — only add. Removing a field or changing its type breaks consumers you have forgotten about. Adding is always safe. This one rule prevents most API pain.
Errors are part of the contract. A consistent error body with a stable machine-readable code is the difference between an integration that handles failure and one that shows a raw 500 to a customer. Design your errors as carefully as your successes.
Paginate everything that can grow. A collection that returns everything works fine with fifty rows and falls over at fifty thousand. Cursor pagination from the start; offset pagination lies once rows are being inserted.
Make writes idempotent. Networks retry. Users double-click. Without an idempotency key you will eventually create duplicate orders, and you will find out from a customer.
Timestamps in UTC, ISO 8601, always. Every time I have seen a local-time timestamp in an API, it has caused a bug. Not sometimes — every time.
On the things people argue about
Whether it is REST or GraphQL matters much less than whether the resources are modelled sensibly. I have seen clean REST and awful REST, clean GraphQL and awful GraphQL, and in every case the deciding factor was whether someone had thought clearly about the domain.
Pick the one your team can operate confidently. Then spend your remaining energy on the naming, the errors and the pagination — the parts that will still be there in three years.
The test
Show the endpoint list to someone who understands the business but not the codebase. If they can guess what each one does, it will age well. If they need the UI in front of them to make sense of it, you have modelled the screen.
That test has never let me down.
Contact Acquiretech Software Solution: info@acquiretechsoftwaresolution.in · WhatsApp +91 80786 33912 · Send an enquiry