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/usersSimple and explicit.
Media type:
Accept: application/vnd.example.v2+jsonUses HTTP representation negotiation.
Header:
X-API-Version: 2Separates version selection from the URI.