Compare the main ways to version an HTTP API — a version in the URI path such as /v1/orders, a query parameter, a custom request header, and media-type versioning via the Accept header. What are the trade-offs?

## What all four have in common Every scheme answers one question: *how does the caller select which contract they want?* The differences are operational — visibility, cacheability, routing, tooling — rather than deep. ## URI path versioning `GET /v1/orders/42`. Strengths: the version is visible in every log line, trace, curl command and support ticket. Gateways route on prefix, so v1 and v2 can be separate deployments with independent scaling and rollback. Caches key on the URL, so correctness is automatic. A developer can paste it into a browser. Docs and SDKs are unambiguous. Weaknesses: the same underlying entity now has two identifiers, which complicates hypermedia links, stored URLs and cross-references. Because the prefix is coarse, teams bump the entire API for a change affecting one endpoint, forcing customers to migrate code they had no reason to touch. ## Query parameter versioning `GET /orders/42?version=2`. Easy to add, still visible and browser-friendly. But it is easy to omit — which makes the default version load-bearing — it conflates contract selection with resource filtering, and shared cache keys depend on parameter normalisation. Rarely a first choice, common as a retrofit. ## Custom request header `X-API-Version: 2` (or a vendor-specific name). URIs stay canonical: one resource, one URL. Versions can be per-resource, so a change to orders does not force a bump for payments. Costs: invisible in browsers and most logs unless deliberately captured; every curl example gets longer; a forgotten header silently selects the default; and shared caches must be told to `Vary` on that header or they will serve one version's body to another version's caller. It also breaks HTTP's own conventions less cleanly than content negotiation, since HTTP already has a mechanism for this. ## Media-type versioning `Accept: application/vnd.github+json; version=3` or `application/vnd.example.order.v2+json`. This is content negotiation used as designed: the URI names the resource, the media type names the representation. Requests use `Content-Type` symmetrically, and the server should reply with the media type it actually produced. Non-negotiable requests yield **406 Not Acceptable**. `Vary: Accept` handles caching — and since caches already vary on `Accept` far more reliably than on custom headers, this is the safest header-based option operationally. Strengths: per-representation granularity, no URI duplication, standards-aligned. Weaknesses: unfamiliarity — many client developers have never set a vendor media type; tooling like browsers and simple HTTP clients default to `*/*`; parsing suffixes and parameters correctly on the server takes care; and documentation is heavier. ## Defaults, and choosing Whatever the mechanism, define what happens when the caller specifies nothing. Two defensible policies: **pin to the oldest supported version** (existing integrations keep working, new ones must opt in) or **reject unversioned requests** (explicit, noisier onboarding). Defaulting to *latest* is the one clearly bad option — every release breaks every lazy client. In practice: URI path for most public APIs where operability and developer familiarity dominate; media-type or header versioning where per-resource evolution and URI stability genuinely matter. The costly mistake is mixing schemes across teams, so the same platform is versioned three ways.