Loading page
About this tool
Compare URL path, query parameter, custom header and media type API versioning — weighted scoring plus migration cost for each.
This tool ranks the four mainstream API versioning strategies — URL path (/v2/), query parameter (?api-version=), custom header (Stripe-Version) and media type content negotiation (Accept: application/vnd.example.v2+json) — against six weighted criteria including HTTP cache friendliness, client simplicity and gateway routing. Each strategy carries a documented migration-cost note and a real-world anchor (Stripe, Azure, GitHub). API designers get a ranked, defensible choice instead of the eternal path-versus-header debate.
Open API Versioning Strategy Chooser on AltFTool — it loads instantly in your browser.
Paste your code or data sample into the workspace.
Pick the format, conversion, or analysis you need.
Copy the polished result straight back into your project.
Path, query, header and media type compared on the same six 0-5 criteria, with a full matrix included.
Each option lists what existing clients must change and how old versions keep working during cutover.
Anchored to shipping designs: Stripe's date-pinned header, Azure's api-version parameter, GitHub's vendor media type.
URL path versioning — a /v1/ or /v2/ segment in the path — is the most widely used because every client, cache and gateway understands a different URL with zero extra configuration. Its cost is that URLs are unstable across majors: every client must rewrite its base URL when v2 arrives, and the version leaks into bookmarks and logs.
Stripe pins each account to the API version current at signup and lets requests override it with the Stripe-Version header, using dates (for example 2024-06-20) rather than v1/v2 numbers. This keeps URLs stable forever and makes upgrades opt-in per account, at the price of gateway and cache logic that must read a request header.
Because two versions of the same URL produce different bodies, a shared cache must be told the response varies by that header — via Vary: Accept or Vary on the custom header (RFC 9110) — or it may serve v1 content to a v2 caller. URL path and query strategies avoid this entirely since each version already has a distinct cache key.
Only for breaking changes — additive changes (new fields, new endpoints) should ship unversioned, and clients must be told to ignore unknown fields. Many teams defer versioning entirely by evolving compatibly, then introduce a version marker the first time a genuinely breaking change is unavoidable; when you deprecate, announce dates with Deprecation and Sunset headers.