APIs
Designing APIs that survive a redesign of the frontend
An API survives a frontend redesign when its resource shapes describe the domain, not the screen. That sounds obvious until you look at most APIs in the wild, where every endpoint mirrors a UI component the team built two years ago. The cost of that coupling is paid every time the design changes — which, on a healthy product, is constantly.
Resource shapes vs. screen shapes
A common anti-pattern: GET /api/dashboard-data returns exactly the fields the dashboard happens to need today, in exactly the nesting the React tree expects. When the design changes, the endpoint has to change, every consumer breaks, and you end up shipping /api/dashboard-data-v2. Multiply by the number of screens, and your API becomes a graveyard of frozen view-models.
The fix is to expose resources, not views. A Project is a Project — it has the same shape whether the dashboard, the settings page, or a future mobile app needs it. Aggregation belongs in the client (or in a thin BFF layer), not in the resource. Yes, this means more requests on first paint. Yes, you fix that with HTTP/2, with smart caching, and with a dedicated aggregator endpoint named for what it aggregates — never named for the screen.
Pagination, idempotency, versioning
Three boring decisions with outsized payoffs:
- Pagination: cursor-based from day one, never offset-based. Offset pagination breaks the moment your dataset grows or you add filtering. Cursors stay stable.
- Idempotency: every mutation accepts an
Idempotency-Keyheader. The first time you have a flaky network and a customer charges twice, you’ll wish you’d done this. - Versioning: in the URL (
/v1/), not in headers. Headers feel cleaner; URL versioning is what teams actually understand and what proxies handle correctly.
None of these are free, but all three pay for themselves in the first year of a serious product. The teams that skip them aren’t saving time — they’re deferring it.
Contract tests as a forcing function
The single biggest accelerator I’ve seen on API teams is contract tests that run on every PR. Not unit tests of the controller, not integration tests of the database — tests that load a fixed set of response fixtures and verify the API still produces them, byte-equivalent, after a change. When the test breaks, the developer is forced to acknowledge: “I’m changing the API contract; do the consumers know?”
Without that forcing function, every PR is a roll of the dice — silent breaking changes ship at the speed of CI, and frontends discover them in production. With it, breaking changes still happen, but they’re deliberate.
If you’re planning an API rewrite or a v2 cutover, the contract-test-first approach is what I’d recommend before any code changes. It’s also worth reading my latency notes on Next.js + Postgres — most API perf problems are downstream of the same database shapes.
READ NEXT
Cutting P95 latency by 60% on a Next.js + Postgres stack
A profiling playbook: which spans actually matter, where the wins hide, and how to measure without lying to yourself.
A pragmatic AWS setup for solo devs and small teams
The minimal stack that gets you to production without a platform engineer — and the upgrade paths to plan for.
Why your landing page converts at 0.8% (and how to fix it)
Five concrete patterns that consistently move the needle — and one that almost everyone ships but rarely tests.