Rethinking Versioning Strategies for Public Web APIs

Introduction

When a service exposes a Product API and prefixes its routes with something like /api/v1, many engineers feel an uneasy tension with the fact that the API itself also carries a semantic version such as 1.2.3. The first component of the semantic version is duplicated in the URL, creating two places where the contract lives. If a breaking change arrives, the team must decide whether to bump the URL path, the version header, or both, and the decision ripples through reverse‑proxy configurations, client SDKs, and documentation. This article unpacks why that tension exists, surveys the dominant practices, and proposes a nuanced way to think about versioning that respects both stability and evolution.

{{IMAGE:1}}

The Core Argument: URL Paths vs. Semantic Versioning

1. URL‑Based Versioning as a Guardrail

Placing a version segment in the path (/v1/) gives a hard boundary that browsers, load balancers, and API gateways can enforce. As avm99963 points out, this approach forces the provider not to break existing contracts until the endpoint is deliberately retired. The path becomes a visible contract marker; a client that still calls /v1/products is guaranteed to receive the behavior defined for version 1, regardless of any internal refactoring.

2. Semantic Versioning Inside the Payload

Semantic versioning (MAJOR.MINOR.PATCH) is traditionally used for libraries where the version is emitted in a header, a response body, or a discovery document. It allows nuanced communication: a PATCH bump signals a bug‑fix, a MINOR bump signals backward‑compatible additions, and a MAJOR bump signals breaking changes. The version lives inside the contract rather than in the URL, keeping the endpoint stable.

3. The Coupling Problem

When both mechanisms are employed, the first number of the semantic version is expected to match the path segment. This creates a coupling that can become confusing:

• A breaking change requires a new path (/v2/…) and a 2.0.0 version string.
• If the API evolves independently (e.g., a security patch), the path stays /v1/ while the version becomes 1.0.1, scattering the version information.
• Teams may feel compelled to keep the path version static even after a major bump, leading to “stuck” v1 APIs that cannot evolve cleanly.

Key Arguments and Supporting Practices

A. Google’s AIP Guidance – A Structured Alternative

Google’s API Improvement Proposals (AIP‑180, AIP‑185) outline a disciplined versioning model that separates API surface from implementation. They recommend:

• URI versioning only for breaking changes – the path includes /v1/, /v2/, etc., but only when the contract itself changes in an incompatible way.
• Header‑based versioning for non‑breaking updates – a custom header like X-API-Version: 1.2.0 conveys minor or patch changes without altering the URL.
• Explicit deprecation metadata – each version advertises its deprecation schedule, allowing clients to plan migrations.

These guidelines illustrate that URL versioning need not be a blunt instrument; it can coexist with finer‑grained version signals.

B. Content‑Negotiation and Media Types

Another pattern sidesteps the URL entirely by leveraging content negotiation. The client requests a specific media type, e.g., Accept: application/vnd.myapi.v2+json. The server then serves the appropriate representation. This keeps the path clean (/products) while still allowing major version differentiation. The downside is that many HTTP clients and proxies do not handle custom media types gracefully, and documentation must emphasize the Accept header.

C. Hypermedia‑Driven APIs (HATEOAS)

Hypermedia APIs embed version information in the links they return. A response might contain a _links object where each link includes a rel and a href that points to the appropriate versioned endpoint. Clients follow these links rather than constructing URLs themselves, which decouples the client from any hard‑coded version segment. While elegant, this approach requires a disciplined hypermedia implementation and can be overkill for simple CRUD services.

D. Single‑Version, Backward‑Compatible Evolution

Some organizations adopt a single‑version policy: the public endpoint never changes (/api/products), and every change is made backward‑compatible. Deprecation is communicated via response headers (Deprecation: Tue, 01 Jan 2025 00:00:00 GMT). This eliminates the need for multiple paths but places a heavier burden on the server to maintain compatibility indefinitely.

Implications for API Design Teams

1. Operational Simplicity vs. Client Clarity – URL versioning simplifies routing and caching but can lead to a proliferation of endpoints. Header or media‑type versioning keeps the surface tidy but demands more sophisticated client logic.
2. Documentation Discipline – When version information lives in two places, documentation must clearly state which version each endpoint corresponds to and how clients discover the current version.
3. Migration Path Planning – Regardless of the chosen strategy, providing a deprecation timeline and automated migration tools (e.g., SDK generators that warn about upcoming major versions) reduces friction for downstream developers.
4. Tooling Support – Modern API gateways (Kong, Envoy, AWS API Gateway) can route based on headers or media types, making non‑path versioning technically feasible without custom reverse‑proxy rules.

Counter‑Perspectives and Trade‑offs

• Pro‑URL Versioning – Critics argue that the path is the most visible contract; developers instantly see which version they are calling, and caching layers treat each version as a distinct resource, avoiding accidental cross‑version cache hits.
• Anti‑URL Versioning – Opponents claim that embedding version in the URL encourages version fatigue: every minor tweak feels like a new endpoint, leading to a sprawling API surface that is hard to maintain.
• Hybrid Approaches – Many large platforms (e.g., Stripe, Twilio) combine URL versioning for major breaks with header‑based feature flags for incremental improvements, striking a balance between clarity and agility.

Conclusion

The tension between /v1/ paths and semantic version numbers is not a flaw but a symptom of trying to satisfy two orthogonal goals: stable routing and expressive contract evolution. By recognizing that versioning can be expressed at multiple layers—URL, header, media type, or hypermedia link—teams can choose the combination that aligns with their operational constraints and client ecosystem. Google’s AIP documents provide a concrete blueprint for a disciplined hybrid model, while content‑negotiation and HATEOAS offer more experimental alternatives. Ultimately, the most effective strategy is the one that makes the version contract explicit, discoverable, and manageable without scattering version information across disparate places.

---

Further Reading

• Google API Improvement Proposals: AIP‑180 – Backwards Compatibility and AIP‑185 – API Versioning
• "Versioning REST APIs" by Microsoft Docs – a practical guide to header‑based versioning: https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-design#versioning
• "Designing APIs for Evolution" – a talk by Kin Lane (API Evangelist) that explores hypermedia and content negotiation: https://apievangelist.com/2020/03/12/designing-apis-for-evolution/