Thanks Bill. Your questions are valid and most of the developers might have when they see this blog post.
Typically, I’d default to the latest stable version (say, v2 if that’s the current one) or maybe even the oldest supported version (v1) to keep legacy clients happy. It depends on your API’s philosophy.
See this blog post : https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
This blog was written by Roy Field [{One of the author of HTTP specification]
Here are few points from him and the interpretion
1. A REST API should never have ‘typed’ resources that are significant to the client.
URL versioning (e.g., /v1/products) implies a type distinction (v1 vs. v2) that clients must understand, which Fielding rejects.
2. A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). Servers must have the freedom to control their own namespace.
Versioning in URLs (e.g., /v1/products) assumes a fixed structure, which Fielding rejects. Clients shouldn’t rely on out-of-band knowledge (like "v1 means version 1")—the server should guide them via hypertext.
3. A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types... all application state transitions must be driven by client selection of server-provided choices.
I suggest for headers (e.g., Accept) over URL versioning, implying the server controls the representation, not the URI structure. URL versioning requires clients to know /v1 vs. /v2 beforehand (out-of-band info), whereas headers let the server provide versioned representations dynamically, aligning with HATEOAS.
4. A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state.
Fielding supports this—versioning belongs in media types or headers, not URIs, as the media type defines how clients process the resource.
Fielding does emphasize that URIs should be stable identifiers for resources (Chapter 5 of his dissertation, if you want the deep dive). The idea is that a resource—like “products”—shouldn’t change its URI just because its representation evolves. When you slap /v1 or /v2 on it, you’re baking the version into the identifier, which ties the resource’s identity to a specific implementation. That’s where the “violation” creeps in: it breaks the principle of timeless URIs and creates tight coupling between clients and specific versions.
URL versioning isn’t “wrong” in a practical sense—it’s just less RESTful. Tons of APIs (like Twitter’s old /1.1/statuses or even parts of AWS) use it and get by fine. It’s more about trade-offs: URL versioning is quick and explicit, but headers align better with REST’s long-term vision and scalability. If you’re running separate services per version, like you suggested, that’s a decent middle ground—though you’ll still face maintenance creep as versions pile up.
Usage
-------------
GitHub’s API is a example for this: they use Accept: application/vnd.github.v3+json and keep /users as a stable endpoint, even as the response format evolves. Stripe does something similar, juggling 10+ versions without cluttering their URLs.
