We need to version our APIs effectively. What is the best strategy or tool for API versioning?

For most REST APIs, I’d recommend a “version only for breaking changes” strategy, with major versions selected explicitly by clients.

Recommended approach

1. Keep non-breaking changes unversioned

• Add optional fields/endpoints.
• Add optional request parameters.
• Fix bugs without changing documented behavior.
• Avoid removing/renaming existing fields.

Microsoft similarly recommends making changes backward-compatible whenever possible and introducing a new version when a breaking change is unavoidable.

2. Use major versions in the URL

GET /api/v1/customers/123
GET /api/v2/customers/123

I'd choose this over header-based versioning for most teams because it's immediately visible in logs, browser requests, documentation, monitoring, and debugging. Both URI- and header-based approaches are established patterns.

3. Don't expose every SemVer number to clients

Internally you can use:

1.4.2
1.5.0
2.0.0

But clients generally select:

v1
v2

rather than having to pin themselves to v1.4.2. Microsoft specifically recommends avoiding overly granular client-selectable versions because it creates too many versions to support.

4. Treat OpenAPI as the contract

Maintain a separate OpenAPI specification for each major API version:

openapi/
  v1.yaml
  v2.yaml

Then use OpenAPI tooling to generate documentation, clients, contract tests, and compatibility checks. OpenAPI supports a contract-first approach and can generate client libraries/documentation.

What tool should you use?

It depends on your architecture:

For example, Kong can route different API versions and manage multiple published versions, while Azure API Management supports publishing multiple API versions side-by-side.

A particularly good model for public APIs

If you're building a large external/public API, I'd consider Stripe's approach rather than simply /v1, /v2, /v3.

Stripe pins customers to a specific API version and allows individual requests to explicitly select another version. Its newer model uses dated releases, with backward-compatible monthly releases and less frequent breaking releases.

That gives you:

Client A → 2026-02-25
Client B → 2026-08-15
Client C → 2027-01-xx

without forcing every customer to upgrade simultaneously.

My default recommendation

For a typical company API, I'd implement:

                    ┌── /api/v1 ── existing clients
Client ── Gateway ──┤
                    └── /api/v2 ── migrated clients
                           │
                    OpenAPI v2 contract

with these policies:

• Breaking change → new major version
• Non-breaking change → same version
• URL versioning → /v1, /v2
• OpenAPI → source of truth for the contract
• Gateway → route versions
• Deprecation period → clearly documented
• Telemetry → identify which clients still use old versions
• Sunset old versions → don't support them indefinitely

The last part is important: multiple versions create real testing and operational cost, so establish a deprecation policy rather than accumulating v1, v2, v3, v4 forever.

If you tell me whether you're using REST, GraphQL, or gRPC, and your stack (e.g. .NET, Java/Spring, Node, Python), I can recommend a concrete versioning architecture and tooling.

Effective API versioning depends heavily on your architectural style, but there is a clear consensus on the best strategies and how they compare.

Top API Versioning Strategies

• URI Path Versioning : Embedding the version directly in the URL path (e.g., /v1/users or /api/v1/users).
  • Pros : Highly visible, easy to test in a browser or logs, simple to route at the load balancer/gateway level, and caching is straightforward per URL.
  • Cons : Technically violates pure RESTful URI design principles because the resource representation shouldn't dictate the endpoint location.
• Request Header Versioning : Passing a custom header (e.g., X-Version: 1 or using an accept header like Accept: application/vnd.mycompany.v1+json).
  • Pros : Keeps the URL clean and strictly adheres to REST principles by treating the version as metadata/representation of the resource.
  • Cons : Harder to test quickly in a browser, requires custom client configuration, and can complicate caching layers.
• Query Parameter Versioning : Passing the version as a parameter in the query string (e.g., /users?version=1).
  • Pros : Easy to implement and test.
  • Cons : Easily forgotten or messed up by caching mechanisms, and generally considered messy for clean API design.

Which Strategy is Best?

• URI Path Versioning is widely considered the best overall strategy for the vast majority of teams. The massive developer experience benefits (visibility, ease of debugging, clear documentation) outweigh the academic purity violation of REST.

Best Practices for Implementation

1. Use Semantic Versioning (MAJOR.$MINOR.$PATCH) : Increment the major version only when making breaking changes. Minor/patch updates should be backward-compatible.
2. Avoid Over-Versioning : Don't bump the version for every minor tweak. Use additive changes (like adding a new optional field) instead of breaking contracts.
3. Establish a Deprecation Policy : Clearly communicate a timeline (e.g., 6 to 12 months) before sunsetting an old version, and return a Sunset HTTP header or deprecation warning in the response headers.

If you'd like, let me know:

• What framework or gateway you are using (e.g., Spring Boot, FastAPI, AWS API Gateway, NGINX)
• Whether you lean toward REST or GraphQL

I can give you a concrete code example or routing setup for your stack.

For most teams, I’d recommend contract-first API versioning with OpenAPI, plus a strict backward-compatibility policy—rather than creating a new v2 for every change.

Recommended strategy

1. Only version for breaking changes.

Keep the same API version when you can make backward-compatible changes:

• ✅ Add a new endpoint
• ✅ Add an optional request field
• ✅ Add a new response field
• ✅ Add a new enum value if clients tolerate unknown values
• ❌ Rename/remove a field
• ❌ Change a field's type
• ❌ Change the meaning of an existing field
• ❌ Make an optional request field required

This keeps migrations manageable. Stripe uses a particularly good model: incremental versions, with compatibility changes separated from genuinely breaking releases.

2. Use explicit versioning for breaking releases.

For a conventional REST API, I'd favor:

/api/v1/customers
/api/v1/orders

/api/v2/customers
/api/v2/orders

Path versioning is easy to understand, debug, document, and route through gateways. Header-based versioning can be elegant, but it is less visible and tends to complicate caching, debugging, and client tooling.

For APIs with many independent consumers, you can instead consider a date-based or header-based version, similar to Stripe:

API-Version: 2026-08-12

That can be excellent when you expect frequent, incremental evolution rather than occasional v1 → v2 rewrites.

The toolchain I'd use

OpenAPI itself doesn't prescribe your API-versioning strategy; it gives you the machine-readable contract from which you can generate documentation, clients, tests, and compatibility checks.

The important part: automate compatibility checks

I'd put this in CI:

Pull Request
     │
     ▼
OpenAPI spec changed
     │
     ▼
Compare against production spec
     │
     ├── Non-breaking → ✅ merge
     │
     └── Breaking → ❌ fail
                         │
                         ▼
                  Require API version
                  + migration plan

This is more valuable than the particular versioning syntax. Your developers shouldn't have to manually decide whether changing a schema is breaking.

Also establish a lifecycle

I'd define something like:

v1 → Current
v2 → Preview
v1 → Deprecated
v1 → Sunset

When introducing v2:

1. Publish the new OpenAPI contract.
2. Run both versions.
3. Document migration differences.
4. Monitor which clients still use v1.
5. Notify those consumers.
6. Give a defined sunset date.
7. Remove v1 only after the agreed support window.

Microsoft similarly recommends that clients explicitly specify the API version rather than silently inheriting behavior that might change.

My preferred architecture

If you're starting from scratch, I'd choose:

REST + /v1 path versioning + OpenAPI + automated breaking-change detection + explicit deprecation/sunset policy.

Then adopt a rule:

Don't create a new API version unless the existing contract cannot remain backward compatible.

If you're building a large public API with lots of external customers, I'd go one step further and consider date-based versions with per-client version pinning, à la Stripe. That scales better than accumulating v1, v2, v3, etc. Stripe specifically designed its system around making upgrades incremental and keeping the cost of old versions contained.

If you tell me your stack (e.g. Java/Spring, .NET, Node, Python, AWS/Azure/Kubernetes) and whether these are internal or public APIs, I can recommend a concrete versioning architecture and tooling setup.

Choosing the best API versioning strategy depends heavily on your architectural style, client ecosystem, and how strictly you want to enforce backward compatibility. There is no single "silver bullet," but rather industry-standard patterns that trade off cacheability, developer experience, and implementation complexity.

Core API Versioning Strategies

• URI Path Versioning : Embedding the version directly in the URL path (e.g., /api/v1/resource).
  • Pros : Highly visible, easy to test in a browser or logs, and straightforward to route at the load balancer/gateway level.
  • Cons : Violates pure REST URI principles (since the URI is supposed to identify a resource, not its representation/version).
• Request Header Versioning : Passing the version via a custom header (e.g., X-API-Version: 1 or using vendor media types in the Accept header like application/vnd.mycompany.v1+json).
  • Pros : Keeps URLs clean and adheres strictly to REST semantic principles regarding content negotiation.
  • Cons : Harder to test quickly in a browser, requires clients to explicitly configure headers, and can complicate caching layers if not configured correctly.
• Query Parameter Versioning : Appending the version as a query string parameter (e.g., /api/resource?version=1).
  • Pros : Easy to implement and easy for clients to override or test on the fly.
  • Cons : Poor cacheability (many CDNs and caches ignore or mishandle query parameters for caching static representations), and it clutters the query space.

Industry Recommendation: Which is "Best"?

• For 90% of Web APIs (REST/JSON): URI Path Versioning (/api/v1/... ) is widely considered the most practical and pragmatic choice. The developer experience is superior because it is transparent, easy to debug, and universally supported by API gateways and testing tools.
• For Enterprise/Hypermedia APIs (HATEOAS): Accept Header Versioning is technically superior and respects REST architecture constraints, though it demands more discipline from client developers.

Best Practices for Implementation

1. Avoid Breaking Changes : Whenever possible, make additive changes (adding optional fields, new endpoints) rather than breaking changes, which lets you delay version bumps.
2. Use Semantic Versioning (SemVer) : Follow major.minor.patch (MAJOR. MINOR. PATCH) for your versions. Increment the MAJOR version only when backward-incompatible changes are introduced.
3. Establish a Deprecation Policy : Communicate deprecations well in advance (e.g., 6 to 12 months notice) via response headers like Sunset: Wed, 11 Nov 2026 00:00:00 GMT or Deprecation: true.
4. Leverage API Gateways : Use tools like Kong, Apigee, AWS API Gateway, or Tyk to handle routing, transformation, and deprecation logging rather than hardcoding version logic deep inside your microservices.

If you'd like, let me know:

• What architecture your API uses (REST, GraphQL, gRPC)?
• Who your consumers are (internal frontends, public third-party developers)?

I can give you a more tailored recommendation and architecture pattern.

There isn't a single "best" tool for API versioning—the best approach is a combination of a versioning strategy, API governance, and supporting tools.

Recommended strategy

The most practical approach for REST APIs is:

1. Only create a new version for breaking changes

   • ✅ Adding optional fields → No new version
   • ✅ Adding new endpoints → No new version
   • ❌ Renaming or removing fields → New version
   • ❌ Changing request/response formats → New version

   This keeps your API stable while avoiding unnecessary version proliferation.

2. Use URL path versioning for public APIs

   /api/v1/customers
   /api/v2/customers
   

   Advantages:

   • Easy to understand
   • Easy to document
   • Works well with gateways, caching, and proxies
   • Widely adopted by public APIs

   Header-based versioning is cleaner from a REST perspective but is harder to debug and test.

3. Maintain backward compatibility whenever possible Instead of:

   {
     "name": "John"
   }
   

   changing to

   {
     "fullName": "John"
   }
   

   Prefer:

   {
     "name": "John",
     "fullName": "John"
   }
   

   Deprecate name first, then remove it in the next major version.

4. Publish deprecation timelines Give consumers time to migrate (for example, 6–12 months for public APIs), communicate end-of-life dates, and provide migration guides. Recent best practices also recommend using HTTP deprecation and Sunset headers where appropriate.

---

Recommended tools

A common enterprise stack is:

• OpenAPI for the API contract
• An API gateway for routing /v1 and /v2
• Pact for consumer-driven contract testing
• CI/CD checks to prevent unintended breaking changes

---

Example lifecycle

v1
 ├── Add optional fields ✔
 ├── Add new endpoint ✔
 ├── Performance improvements ✔
 └── Bug fixes ✔

v2
 ├── Remove deprecated fields
 ├── Change authentication
 ├── Redesign response structure
 └── Breaking changes

---

For microservices

Avoid versioning your internal APIs unless you have independent consumers that require long-term compatibility. Many internal service changes can be coordinated through deployments and contract testing instead of maintaining multiple API versions. Reserve explicit versioning for stable contracts with external or loosely coupled consumers.

Overall recommendation

If you're starting a new REST API today, a strong default is:

• Version only for breaking changes
• Use URL path versioning (/api/v1/...)
• Define contracts with OpenAPI
• Use contract testing (Pact)
• Manage routing through an API gateway such as Kong or Apigee
• Deprecate versions gradually with clear migration guidance

This combination is widely used, easy for consumers to understand, and scales well as your API evolves.

The "best" strategy for API versioning depends on your consumer base, but industry consensus heavily favors URI Path Versioning for public-facing APIs and Header-Based (or Date-Based) Versioning for advanced enterprise platforms.

Rather than relying on a single "magic" tool, effective versioning is a combination of a predictable routing strategy, an API gateway, and strict lifecycle management.

Phase 1: Choosing a Strategy

• URL Path Versioning (e.g., /api/v1/resource)
  • Best for: Public REST APIs, multi-tenant systems, and general ease of use.
  • Pros: Highly visible, incredibly easy to debug in logs or browsers, and natively cache-friendly with CDNs (since distinct URLs map cleanly to distinct cache keys).
  • Cons: Strictly violates purist REST/HATEOAS principles because the resource URI changes per version.
• Header-Based / Custom Media Type Versioning (e.g., Api-Version: 2 or Accept: application/vnd.company.v2+json)
  • Best for: Enterprise/B2B platforms striving for clean, resource-centric URLs.
  • Pros: Keeps URLs pristine and stable; aligns closer with formal HTTP content negotiation specifications.
  • Cons: Harder to test ad-hoc in a standard browser, complicates edge caching configuration (requires proper Vary headers), and adds friction for third-party developers.
• Date-Based Versioning (e.g., Api-Version: 2026-06-01 popularized by Stripe)
  • Best for: Massive developer platforms with hundreds of granular, evolving fields.
  • Pros: Allows clients to pin themselves to a specific release date, ensuring nothing breaks unexpectedly.
  • Cons: Significant architectural and code complexity to maintain backwards compatibility mapping inside your backend.

Phase 2: The Modern Toolchain

You don't need a single standalone tool for versioning; instead, combine these layers:

1. API Gateway (The Traffic Router): Use an edge layer like Kong, AWS API Gateway , or Azure API Management to parse paths or headers and route requests to the correct underlying service deployment without tightly coupling your server code.
2. Framework Routing (The Code Manager): Implement internal routing inside your application framework (e.g., .NET 's ASP.NET Core API Versioning , Spring Boot, or Express routers) to split controllers or transformers rather than duplicating whole microservices.
3. Specification & Documentation (The Contract): Maintain clear specifications using OpenAPI / Swagger , generating separate, clear documentation portals for each active version.

Phase 3: Golden Rules of Execution

• Define Breaking vs. Non-Breaking: Only bump your major version for actual breaking changes (removing fields, changing data types, dropping endpoints). Adding optional fields or new endpoints is non-breaking and doesn't require a new version.
• Use Standards-Based Deprecation: Adopt standard signaling headers like the standard Deprecation Header (RFC 9745) and Sunset Header (RFC 8594) to automatically warn consumers when an old path is nearing retirement.
• Support a Strict Window: Maintain at least two concurrent major versions (current + previous) and enforce a predictable 6-to-12-month deprecation lifecycle window based on actual traffic telemetry.

If you can share whether your API is publicly consumed by third parties or internal-only , I can give you a more tailored recommendation on path vs. header versioning.

There isn't a single "best" API versioning tool because versioning is primarily a design strategy rather than a software feature. The right approach depends on whether your APIs are public, internal, REST, GraphQL, or gRPC.

For most REST APIs, a practical strategy is:

1. Version only for breaking changes

Don't create a new version every time you add a field or endpoint. A new version should only be introduced when existing clients would break, such as:

• Removing or renaming fields
• Changing response formats
• Changing required request parameters
• Altering the meaning of existing data

Backward-compatible additions (new optional fields, new endpoints) generally do not require a new version.

2. Use URL path versioning for most public APIs

Example:

GET /api/v1/customers
GET /api/v2/customers

This is the most widely adopted approach because it is:

• Easy for developers to understand
• Easy to document
• Easy to route through API gateways
• Friendly to caching and debugging

While header-based versioning is arguably more RESTful, many organizations choose URL versioning because of its operational simplicity.

3. Maintain compatibility

Within a major version:

• Only add optional fields
• Never remove fields
• Don't change data types
• Don't change response semantics

For example:

Good (non-breaking)

{
  "id": 1,
  "name": "Alice",
  "email": "[email protected]"
}

↓

{
  "id": 1,
  "name": "Alice",
  "email": "[email protected]",
  "phone": "1234567890"
}

Breaking

{
  "customerName": "Alice"
}

instead of

{
  "name": "Alice"
}

4. Deprecate before removing

A healthy API lifecycle looks like:

• Release v2
• Continue supporting v1
• Announce deprecation
• Provide migration documentation
• Retire v1 after a published timeline

This gives consumers time to migrate without disruption.

Recommended tools

Rather than using a dedicated "versioning tool," combine these technologies:

Contract testing is especially valuable because it helps prevent accidentally introducing breaking changes between services.

If you're using specific frameworks

• Spring Boot (Java): Spring MVC + OpenAPI, optionally Spring Cloud Gateway
• ASP.NET Core: Microsoft.AspNetCore.Mvc.Versioning
• Node.js/Express: express + OpenAPI + gateway-based routing
• FastAPI: APIRouter with versioned prefixes
• NestJS: Built-in API versioning support

Recommended architecture

A robust production setup often looks like:

Client
   │
API Gateway
   │
 ├── /v1 → API v1
 └── /v2 → API v2

CI/CD
   │
OpenAPI validation
   │
Contract tests (Pact)
   │
Deployment

This allows you to evolve APIs independently while protecting existing consumers.

Recommendation: If you're building REST APIs today, use URL path versioning (/v1, /v2), introduce new versions only for breaking changes, publish OpenAPI specifications, and use contract testing (e.g., Pact) plus an API gateway for routing. This combination is straightforward to adopt and scales well for both internal and public APIs.

Choosing the "best" API versioning strategy depends heavily on your consumer base and architecture, but industry consensus strongly favors URI Path Versioning for public-facing or multi-consumer APIs due to its simplicity, transparency, and ease of debugging.

The primary strategies, their trade-offs, and proven lifecycle practices help define a robust approach.

1. Core Versioning Strategies Compared

• URI Path Versioning (/v1/resources)
  • Best for: Public-facing APIs, external developers, and browser-based testing.
  • Advantages: Extremely visible, simple to route in code/gateways, and integrates natively with caching mechanisms and CDNs.
  • Disadvantages: Technically clutters the URL (violating strict REST resource-identity principles) and causes "URL sprawl" over time.
• Header-Based Versioning (API-Version: v1 or via Content Negotiation Accept: application/vnd.company.v1+json)
  • Best for: Enterprise ecosystems, internal microservices, and APIs with highly sophisticated consumers.
  • Advantages: Keeps URLs clean and resource-focused, aligning closer to academic REST specifications.
  • Disadvantages: Harder to discover, difficult to test directly in a browser, and requires careful configuration of the Vary header to avoid caching bugs.
• Query Parameter Versioning (/resources?version=1)
  • Best for: Rapid-iteration internal APIs or quick prototypes.
  • Advantages: Easy to add without altering routes.
  • Disadvantages: Can be easily overlooked in documentation, prone to cache key misses, and feels informal for public consumers.
• Date-Based Versioning (2026-06-01 via headers)
  • Best for: High-volume, hyper-evolving platform APIs (pioneered by companies like Stripe).
  • Advantages: Gives granular, per-request control over breaking changes without forcing massive version jumps.
  • Disadvantages: High implementation complexity; the backend must support transformation and mapping layers for every active date.

2. Best Practices for API Lifecycle Management

The best version is often the one you never have to release. Prioritizing backward compatibility and standard lifecycle management reduces friction:

1. The Expand and Contract Pattern: Prefer additive, non-breaking changes first (e.g., adding optional fields). Only bump the major version when a true breaking change (deleting or renaming a required field, changing a data type) is unavoidable.
2. Pick One Strategy and Stick to It: Avoid mixing path versioning on some endpoints and header versioning on others. Consistency is vital for developer experience.
3. Set a Clear Deprecation Policy: Give consumers at least 6 to 12 months notice before shutting down an old version. Use standard response headers like Sunset: Wed, 11 Nov 2026 00:00:00 GMT to programmatically signal retirement.
4. Automate Compatibility Checks: Use tools in your CI/CD pipeline (such as OpenAPI contract testing and linting tools) to ensure accidental breaking changes don't slip into production builds.

If you can share whether your API is public or internal and roughly how many active clients you have, I can help you choose the ideal strategy and map out a deprecation timeline.

Effective API versioning depends on your need for visibility, caching efficiency, and strict REST compliance. The most widely adopted and recommended strategy for most APIs is URI Path Versioning , but modern alternatives offer better architectural cleanliness.

Top API Versioning Strategies

1. URI Path Versioning (e.g., ://api.com)
   • Pros: Highly visible, easy to debug, easy to route in code, cache-friendly.
   • Cons: Violates the REST principle that a URI should represent a unique resource (v1/users and v2/users are the same resource).
   • Best For: Public APIs, simplicity, rapid adoption.
2. Header-Based Versioning (e.g., X-API-Version: 2)
   • Pros: Keeps URLs clean, adheres better to REST principles, allows content negotiation.
   • Cons: Harder to test in a browser, more complex for developers, tricky with caching.
   • Best For: Internal or private partner APIs.
3. Media Type/Accept Header Versioning (e.g., Accept: application/vnd.app.v2+json)
   • Pros: Often considered the "highest" form of REST by purists.
   • Cons: High implementation complexity.
4. API Evolution (No Versioning)
   • Description: Avoid breaking changes entirely by adding new fields, making optional fields, or creating new endpoints only when necessary, rather than bumping the whole API.
   • Best For: GraphQL or internal systems with high control over consumers.

Recommended Tools for API Versioning

• OpenAPI (Swagger): The standard for defining and documenting APIs. Use it to document versioned paths or headers and generate client code.
• Postman: Essential for testing and documentation. It supports versioning by allowing you to create different collections or API elements for different versions.
• Kong Gateway: Open-source API gateway that allows routing different API versions to different backend services.
• AWS API Gateway: Handles versioning using stages, allowing v1 to point to a different Lambda than v2.
• Azure API Management: Manages versions, revisions, and policies.

Best Practices

• Use Semantic Versioning: Use major.minor.patch (e.g., v1.2.0) to clearly indicate breaking changes (Major).
• Use URL Versioning for Breaking Changes: Only create a new v2 if it's a major, non-backwards compatible change.
• Plan Deprecation: Always have a plan for deprecating old versions, such as returning Sunset or Warning headers.
• Default Version: Always provide a default version for requests that do not specify one.

To provide a more tailored recommendation, could you tell me:

• Is this a public API or internal?
• How often do you anticipate breaking changes?
• What is your current technology stack (e.g., .NET, Node.js)?

I can then tell you which tool works best for your team.

The best API versioning strategy depends on who consumes your API and how often you expect breaking changes. There is no universal "best tool," but there are well-established best practices.

Recommended strategy

For most REST APIs, URL path versioning is the most practical and widely adopted approach:

GET /api/v1/users
GET /api/v2/users

Why it's recommended:

• Easy for developers to understand.
• Works well with API gateways, proxies, and caching.
• Makes documentation straightforward.
• Allows multiple versions to coexist during migration.

When should you create a new version?

Only introduce a new version for breaking changes, such as:

• Removing or renaming fields
• Changing response formats
• Changing request parameters
• Modifying endpoint behavior in a way that breaks existing clients

For backward-compatible additions (new optional fields, new endpoints), continue using the same version.

Versioning approaches

For public APIs, URL path versioning is generally the safest default.

Best practices

• Keep old versions available during a migration period.
• Publish clear migration guides between versions.
• Announce deprecations well in advance.
• Avoid changing behavior within the same version.
• Make additive changes (new optional fields, endpoints) instead of breaking existing contracts whenever possible.

Tools for API versioning

Versioning itself is a design practice rather than a standalone tool, but these platforms make managing versions easier:

• API Gateways

  • Kong
  • Apigee
  • AWS API Gateway
  • Azure API Management
  • NGINX

• API Documentation

  • OpenAPI (Swagger)
  • Redoc

• Contract Testing

  • Pact (helps verify that API changes remain compatible with consumers)

• Schema Management

  • OpenAPI versioning
  • Protocol Buffers (for gRPC APIs)

Example version lifecycle

v1  -------------------------------> (Deprecated)

            \
             \
v2            ---------------------> (Current)

                    \
                     \
v3                  -----> (Future)

This allows existing clients to remain on v1 while new clients adopt v2, giving consumers time to migrate.

Recommendation: If you're building a REST API for external or long-lived clients, use URL path versioning (/v1, /v2), introduce new versions only for breaking changes, maintain backward compatibility whenever possible, and pair versioning with good documentation and contract testing. This approach is widely adopted because it balances simplicity, clarity, and operational ease.