Designing APIs That Don't Need a Rewrite in a Year

We've inherited enough poorly-aging APIs to notice a pattern: it's rarely a single catastrophic decision that forces a rewrite, but a handful of shortcuts made under early deadline pressure that compound over time.

Version from day one

Adding versioning after your first breaking change is far more painful than building it in from the start. Even a simple /v1/ prefix gives you room to evolve without breaking existing consumers.

Design around resources, not endpoints for specific screens

APIs built to match a specific UI screen tend to require new endpoints for every new screen. Resource-oriented design supports more use cases without proliferating endpoints.

• Model resources and relationships, not front-end screens
• Support filtering, sorting and pagination consistently everywhere
• Return consistent error shapes across every endpoint

Document as you build, not after

APIs without current documentation accumulate undocumented behavior that becomes a de facto contract nobody agreed to. Tools like OpenAPI make this cheap enough to skip only through habit, not necessity.

Frequently Asked Questions