Clients don't upgrade in sync. APIs must evolve without breaking them. Versioning strategies each have tradeoffs.

URL versioning/v1/usersHeader versioningAccept: v2Query param?version=2No version, additive onlyVisible, cache-friendlyClean URLsDebuggableNever breakURL proliferationCache complexityFeels hackyDiscipline required
API versioning strategies with tradeoffs
Advertisement

URL path versioning

/v1/users. Visible. Cache-friendly. Many APIs use it. But every version = new URL space.

URL path versioning

/v1/users. Visible. Cache-friendly. Many APIs use it. But every version = new URL space.

Advertisement

Header versioning

Accept: application/vnd.myapp.v2+json. Cleaner URLs. Caches need Vary header. Confusing for casual API users.

Content negotiation

Server + client agree on version via Accept + Content-Type. Advanced pattern; not universal support.

Additive-only evolution

Never remove fields. Never change types. Only add new fields. Old clients keep working. Requires discipline.

Deprecation policy

Publish deprecation dates. Warn in responses (Deprecation: true header). Provide migration guide. Communicate.

URL versioning is pragmatic. Additive-only is elegant. Communicate deprecations aggressively.