Versioning an API in the URL Is the Most Honest Option, Not the Best One
Key takeaway: Every API versioning strategy is a trade-off between visibility, client effort, and long-term maintainability, and the right choice depends on who your clients are and how much control you have over them.
The Three Main Strategies and Their Trade-Offs
URL versioning — /v1/orders, /v2/orders — is the most visible and explicit approach. It is immediately obvious to any client which version they are calling, it is trivial to route and to test, and it is the easiest for a new developer to understand. Its cost is that it lives permanently in the URL, accumulating versioned endpoints that never get cleaned up, and it makes the API surface visibly larger and more cluttered over time.
Header-based versioning — a custom header like Accept-Version: 2 — keeps the URL clean and stable, which is appealing, but it is invisible to anyone inspecting a request or a log line, it is easy for a client to forget to send, and it is harder to discover and to debug, since the version is not visible in the URL that appears in logs and documentation.
| Strategy | Visibility | Client effort | Long-term clutter |
|---|---|---|---|
| URL versioning | High | Low | High |
| Header versioning | Low | Medium | Low |
| Content negotiation | Medium | Medium | Low |
Content negotiation — using the Accept header to request a specific media type, like application/vnd.myapi.orders.v2+json — is the most standards-aligned and flexible approach, allowing different representations of the same resource to coexist, but it is also the most complex to implement and to explain, and it requires clients to be more sophisticated about how they construct requests.
What Actually Drives the Right Choice
The most important factor is who your clients are and how much control you have over them. An internal API consumed by a small number of teams you can coordinate with directly can afford a cleaner strategy like header or content negotiation, because you can communicate the requirement and help clients migrate. A public API consumed by a large, unknown, and uncoordinated set of external clients benefits from the visibility and simplicity of URL versioning, because you cannot rely on every external client correctly implementing a more subtle mechanism.
The frequency of breaking changes matters too — an API that changes rarely can tolerate a cleaner but more complex strategy, while an API that changes frequently will find the explicit clarity of URL versioning worth its clutter, since the alternative is subtle versioning bugs from clients silently using the wrong version.
The Practical Middle Ground
Many APIs use URL versioning as the primary mechanism precisely because its honesty and simplicity outweigh its clutter for most real-world cases, and the clutter is manageable if versioned endpoints are actually retired on a defined schedule rather than left to accumulate forever — a version that is explicitly deprecated and removed after a documented window keeps the surface from growing without bound.
The Bottom Line
Choose URL versioning when you have many external clients you cannot coordinate with and value visibility and simplicity over cleanliness, and consider header or content negotiation when you control your clients and can communicate a more subtle mechanism reliably. Whatever you choose, retire old versions on a defined schedule rather than letting them accumulate indefinitely.
