API Versioning Strategies: What We Use and What We Stopped Using

We have maintained APIs with external consumers for eight years. We tried four versioning strategies. Two worked. Two created pain.

URL path versioning (/v1/users, /v2/users): simple to understand, clean routing, clear documentation. The problem: maintaining multiple versions is expensive. Bug fixes need applying to all live versions. After two years with three live versions, maintenance was unsustainable. Our verdict: works if you support at most two versions with a twelve-month deprecation window.

Header versioning (Accept: version=2): cleaner URLs. Everything else was worse. Integrators forgot the header constantly. Debugging was harder without the version visible in the URL. Support load doubled. Abandoned after six months.

Query parameter versioning (/users?version=2): visible in URLs but felt hacky. Complicated CDN caching. Migrated to URL versioning within a year.

Additive changes only (no versioning): our current default for external APIs. New fields added, new endpoints added, but nothing is removed or renamed. Every integration written on day one still works years later. Zero version management overhead. The trade-off: response payloads grow over time and deprecated fields linger. We manage this with clear documentation distinguishing current from legacy fields.

For internal APIs consumed by our own frontends, we use URL path versioning because we control both sides and can coordinate migrations.

The key insight: most "breaking changes" can be redesigned as additive changes with creativity. Add a new field with the new behavior. Keep the old field. Document which is preferred. When a genuine breaking change is unavoidable, use URL versioning with a twelve-month sunset.

A practical tip for the additive-only approach: maintain a machine-readable changelog that lists every field addition with the date it was introduced. Integrators can subscribe to this changelog and update their implementations at their own pace. This gives you the transparency of versioning without the maintenance burden of supporting multiple API versions simultaneously.

Our recommendation: start additive-only and resist the urge to version. Keep it simple. Your integrators will thank you.