Choosing a strategy
Putting them side by side
The previous three lessons covered three versioning strategies. Each one works. Each one has tradeoffs. Let’s compare them directly:
| Criteria | URL Path | Header | Query Param |
|---|---|---|---|
| Visibility | In every URL | Hidden in headers | In URL (but mixed) |
| Caching | Simple (different URLs) | Needs Vary header | Mostly simple |
| Routing | Separate route groups | Branching in handlers | Branching in handlers |
| Client effort | Change all URLs | Change one header | Add param to all URLs |
| Convention | Most common | Used by GitHub, Stripe | Rare |
| Discoverability | High | Low | Medium |
Why most teams choose URL path versioning
Looking at this table, URL path versioning wins on the criteria that matter most in day-to-day work.
Convention. It’s what developers expect. When someone looks at your API docs, they look for /v1/ or /v2/. Using something unconventional creates confusion before anyone even makes their first request.
Simplicity. No header parsing, no Vary headers, no branching inside handlers. Each version is a separate set of routes. The code structure mirrors the API structure. What you see in the file system is what you see in the URLs.
Debugging. “The client calls /v2/books and gets the wrong response.” Compare that to: “The client calls /books with X-API-Version: 2 and gets the wrong response.” The first one is easier to reproduce, log, and debug. You can paste it in a browser and see what happens.
Caching. Different URLs mean different cache entries. CDNs work out of the box. No Vary headers to configure, no special setup, no footguns.
When to consider alternatives
That said, URL path versioning isn’t always the right choice.
Header versioning makes sense when you have a small number of sophisticated API consumers, like partner integrations or internal services, who can manage headers. GitHub and Stripe use this because their clients are developers building integrations, not casual users.
Query parameter versioning works for internal APIs or temporary experiments. If you’re A/B testing a response format before committing to a new version, query parameters let you do that without creating new routes.
No versioning at all is fine for APIs with a single consumer under your control. If you deploy the API and frontend together, you can make breaking changes in coordinated releases. There’s nobody else to break.
This course uses URL path versioning
The rest of this course uses URL path versioning because it’s the most common, most practical, and most beginner-friendly approach. But the principles we’ll cover, things like backward compatibility, deprecation, and sunset timelines, apply regardless of which strategy you choose.
Now that we’ve picked a strategy, it’s time to actually build it. In the next section, we’ll create v2 alongside v1 and keep them both running at the same time.
Exercises
Exercise 1: Your API has 50 endpoints and 200 external clients. Which versioning strategy would you choose? Why?
Exercise 2: Your API has 3 endpoints and 1 internal frontend. Do you need versioning at all?
Exercise 3: A partner asks for the API version in a header instead of the URL. How would you handle this request?
What is the most important factor when choosing a versioning strategy?