Versioning Strategies

Common strategies include URI versioning such as /v1/users, query parameters, custom media types, and header-based versioning.

URI versioning is highly visible and easy to route and document. Media-type versioning is more aligned with representation negotiation but can be less discoverable. Header versioning keeps URIs stable but makes requests harder to inspect casually.

There is no universal best strategy. Choose a strategy based on compatibility requirements, tooling, deployment architecture, and consumer expectations.

Strategies
URI: /v1/users
Simple and explicit.
Media type: Accept: application/vnd.example.v2+json
Uses HTTP representation negotiation.
Header: X-API-Version: 2
Separates version selection from the URI.