Why Versioning Exists

Your API is a public contract. Once consumers depend on it, you cannot break it without consequences. Versioning lets you evolve the API while keeping existing integrations alive. Pick a strategy before you ship — changing it later is painful.

The Three Main Strategies

URI versioning — the most common approach:

GET /v1/users
GET /v2/users

Pros: visible, cacheable, easy to test in a browser. Cons: pollutes the URI, violates the idea that a URI identifies a resource not a version.

Header versioning:

GET /users
Accept: application/vnd.myapp.v2+json

Pros: keeps URIs clean, semantically correct. Cons: invisible in browser, harder to test without tooling.

Query parameter versioning:

GET /users?version=2

Pros: easy to add. Cons: query params are for filtering not routing — semantically wrong and breaks caching.

Practical Advice

Use URI versioning unless you have a strong reason not to. It is explicit, tooling-friendly, and most API consumers expect it. Always document your deprecation timeline — give consumers at least six months before sunsetting a version. Return a Sunset response header to signal impending removal.