3 API Versioning Guides, Compared

The API ships next month and someone has to decide whether the version goes in the path, in a header, or in the media type. It is a twenty-minute decision that you live with for years, because changing it later means breaking every client that already integrated.

The frustrating thing is that the debate is thoroughly documented and almost entirely context-free. Purists point out, correctly, that /v1/users gives one resource two identifiers and violates a REST principle. Practitioners point out, equally correctly, that Stripe, GitHub, and Google Cloud all put versions in paths and their consumers cope fine. Both sides are arguing about a question that only resolves once you say who your consumers are.

How to judge a versioning approach

Who consumes it? A public API used by third parties you cannot contact has different constraints from an internal API consumed by two teams you sit next to.

How is it cached? Distinct URIs cache trivially. Header-varying responses require getting Vary right at every layer, including CDNs.

How is it debugged? A version in a path is visible in a browser address bar and a server log. A version in a header is not.

How is it routed? Path-based versions can be split at a gateway or load balancer without reading headers, which matters when v1 and v2 are separate deployments.

The comparison

Facts checked August 2026; plans can change.

Lonti: URL vs Header vs Media Type versioning

Lonti’s piece is the cleanest explanation of the three mechanisms next to each other. If you do not yet know what media type versioning even is — the version travelling in the Content-Type or Accept header rather than the path — this is the fastest way to understand all three options before forming a preference.

It is a vendor blog. The analysis is sound, and it is still marketing-adjacent content, so weigh recommendations against your own constraints.

Microsoft REST API Guidelines

This is the heavyweight: a published, versioned, openly maintained set of API guidelines that a very large organisation actually follows. Its real value in an argument is that it is citable — “we are following the Microsoft guidelines” ends a debate faster than three engineers’ opinions.

It is also a full guideline document covering naming, errors, pagination, and much more. For a single versioning decision it is a lot of reading, and adopting one section of someone else’s standard while ignoring the rest is its own kind of inconsistency.

DigitalAPI: REST API versioning strategies

DigitalAPI’s guide is organised the way the decision actually feels: here is each strategy, here is what it costs, here is when to use it. The recurring conclusion across sources like this — URI versioning for public APIs because it is simple and cache-friendly, header or media type for internal APIs that want clean canonical URIs — is a defensible default.

It is written for people evaluating API management platforms, so the surrounding context assumes a larger governance apparatus than a small team has.

API Versioning Strategy Advisor

Ours turns the reading into a decision. You describe your API’s audience and typical consumers, and it recommends a versioning strategy — URI, header, or query parameter — with the reasoning behind the recommendation, so you get a starting position and the argument for it rather than a survey of options. It runs entirely in your browser.

Two honest limits. It gives you an opinion, not a standard: it will not enforce anything, generate a spec, or check what your existing endpoints already do. And it reasons from the inputs you provide, so if you mischaracterise your consumers — describing a de facto public API as internal — you will get a confident recommendation for the wrong thing.

Which one to pick

• If you need to understand the three mechanisms before choosing, read Lonti.
• If you need something citable in a design review, use the Microsoft guidelines.
• If you want pros and cons laid out per strategy, read DigitalAPI.
• If you want a recommendation for your specific situation in under a minute, use ours.

How to do it with API Versioning Strategy Advisor

1. Open the API Versioning Strategy Advisor.
2. Describe your consumers honestly — including the ones who integrated without telling you.
3. Read the recommendation and its reasoning, then check it against how you actually cache and route. More developer tools are in the tools directory.

You might also need

• REST Endpoint Namer — for the path design that sits below the version decision.
• HTTP Status Code Reference — for signalling deprecation correctly once v1 is on its way out.

Frequently asked questions

Is there a free API versioning guide that doesn’t need an account?

Yes — all three references above are freely readable, and the Microsoft guidelines are open on GitHub. Ours needs no account because the site has no signup at all.

Is URI versioning really “wrong”?

It conflicts with the principle that a resource has one canonical identifier, which is a real objection. It is also what most widely used public APIs do, because it is visible, cacheable, and routable. Treat it as a trade-off you make deliberately rather than an error.

How long should an old version be supported?

Long enough that consumers can migrate, and communicated in advance rather than announced at cutoff. RFC 8594’s Sunset HTTP header exists precisely so a deprecation date can be delivered in the response itself.

Final thought

Pick from your consumers, not from the principle. Whoever cannot be emailed about a breaking change is the constraint that should decide it.

Try the free API Versioning Strategy Advisor