API Versioning: Managing Change Without Breaking Existing Clients

A practical guide to API versioning — the strategies and tooling for evolving an API over time without breaking the clients already depending on it — covering versioning strategies (URI, header, query string, content negotiation), the additive-change discipline that reduces how often versioning is even needed, ASP.NET Core's Asp.Versioning package, deprecation and sunset policies, and how this connects to the REST, GraphQL, gRPC, and event-driven contracts covered elsewhere in this series.

---

Table of Contents

1. Introduction
2. Why Versioning Is Necessary At All
3. The First Line of Defense: Additive, Backward-Compatible Changes
4. URI Versioning
5. Header Versioning
6. Query String Versioning
7. Content Negotiation (Media Type) Versioning
8. Implementing Versioning in ASP.NET Core
9. Versioning Strategy Beyond REST
10. Deprecation and Sunset Policy
11. Semantic Versioning vs. API Versioning
12. Versioning and Client SDKs
13. Common Pitfalls
14. Quick Reference Table
15. Conclusion

---

Introduction

API versioning is the discipline of evolving an API's contract over time — adding capabilities, fixing design mistakes, restructuring resources — without breaking the clients that are already, currently depending on its existing behavior. This series' REST guide introduced the topic and named URI versioning as the most common default; this guide gives the full treatment: every major versioning strategy, the additive-change discipline that reduces how often a version bump is even necessary in the first place, concrete ASP.NET Core implementation, and how the same underlying problem shows up — with different specific mechanisms — across GraphQL, gRPC, and event-driven contracts covered elsewhere in this series.

/api/v1/users   →   the version this series' REST guide used as its example
/api/v2/users   →   a new, breaking revision, coexisting alongside v1 for clients not yet migrated

The core tension every versioning strategy has to manage is the same: your API needs to change and improve over time, but a client that integrated against it last year, and hasn't touched their code since, needs to keep working exactly as it did the day they wrote it — until they decide to migrate, not until you decide to stop supporting the old behavior out from under them.

---

1. Why Versioning Is Necessary At All

Not every change is breaking — but some genuinely are

Adding a new, optional field to a response         → NOT breaking (Section 2)
Adding a new endpoint                                → NOT breaking
Removing a field a client currently reads             → BREAKING
Renaming a field                                       → BREAKING
Changing a field's type (string → number)               → BREAKING
Changing validation rules to reject previously-valid input → BREAKING
Changing the meaning of an existing field, even if the shape stays the same → BREAKING

A breaking change is any change that would cause a well-behaved, already-deployed client — one that was written correctly against the previous contract and hasn't been updated — to start failing or behaving incorrectly. Versioning exists specifically to let you make breaking changes without an existing client having to update on your timeline; it doesn't help with (and shouldn't be reached for to compensate for) changes that were never actually necessary to make in a breaking way in the first place.

The cost of getting this wrong in either direction

Too eager to version:  every minor addition becomes v2, v3, v4... clients constantly need to migrate,
                        even though most of those changes were never actually breaking
Too reluctant to version: breaking changes ship silently, into an existing version, breaking clients
                            with no warning and no migration path

Both extremes are genuine failure modes, not just theoretical ones — an API that bumps its major version for every trivial addition trains clients to distrust version numbers and to delay upgrading out of versioning-fatigue; an API that makes breaking changes without ever bumping a version teaches clients they can never safely trust that the contract they integrated against will still work tomorrow. The discipline in Section 2 — maximizing what counts as additive rather than breaking — is what keeps an API mostly out of the "constantly versioning" failure mode, reserving actual version bumps for genuinely necessary breaking changes.

---

2. The First Line of Defense: Additive, Backward-Compatible Changes

This is the same principle repeated throughout this series, applied here at its origin

As emphasized in this series' Database Migrations, GitOps, Kafka, and Event-Driven Architecture guides, preferring additive, backward-compatible changes over breaking ones is a recurring theme precisely because it originates here, in API contract design, and propagates outward to every other system that has to maintain a contract over time.

What counts as safely additive for a REST API

// v1 response
{ "id": 42, "name": "Wireless Mouse", "price": 29.99 }

// A NEW field added — existing clients that don't know about "discountPercent" simply ignore it
{ "id": 42, "name": "Wireless Mouse", "price": 29.99, "discountPercent": 10 }

• New, optional fields in a response — a client written against the old shape simply doesn't read the new field; nothing about its existing behavior changes.
• New endpoints — an entirely new capability doesn't affect any client not yet using it.
• New, optional query parameters or request fields — as long as omitting them preserves the previous default behavior exactly.
• Widening a validation rule (accepting input that was previously rejected) — a client sending previously-valid input is unaffected; only new, previously-invalid input is newly accepted.

What is never safely additive, no matter how it's framed

// ❌ Removing a field a client might be reading
{ "id": 42, "name": "Wireless Mouse" } // "price" is gone

// ❌ "Just" renaming a field — still breaking, despite feeling minor
{ "id": 42, "productName": "Wireless Mouse", "price": 29.99 } // "name" → "productName"

Removing a field, renaming a field, changing a field's type, or narrowing a validation rule (rejecting input that used to be accepted) are all genuinely breaking, regardless of how small or well-intentioned the change feels — this is precisely the class of change that requires either a genuine version bump, or the expand/contract migration technique covered next.

Expand/contract as an alternative to bumping the version, for a single field

Step 1 (expand): add the NEW field name alongside the old one; both present, both populated
Step 2 (migrate): update documentation, notify clients, give them time to migrate to the new field
Step 3 (contract): once confident no client still reads the old field, remove it — WITHOUT a version bump,
                     since by this point removing it doesn't actually break anyone

This is the same expand/contract pattern covered in this series' Database Migrations guide, applied directly to an API's response shape — for a single field-level change, this can be a lighter-weight alternative to a full version bump, deferring the "breaking" moment until it's genuinely safe, rather than forcing every client through a version migration for what's ultimately a small, single-field change.

---

3. URI Versioning

The most common, most visible strategy

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

As introduced in this series' REST guide, embedding the version directly in the URL path is the most widely adopted strategy in practice — it's immediately visible in logs, browser history, and API documentation, requires no special client tooling (a version-specific URL works with a plain browser, curl, or any HTTP client with zero special configuration), and is trivially cacheable by any HTTP-aware cache or CDN, since the URL itself fully identifies the resource.

The genuine downside: it's technically "impure" REST

REST theory: a URI identifies a RESOURCE, not a version of an API
/api/v1/users/42 and /api/v2/users/42 — are these the "same resource," or two different ones?

Purists point out that a URI is supposed to identify a resource, and the version is arguably a concern of the API surface, not the resource's identity — in strict REST terms, /api/v1/users/42 and /api/v2/users/42 could be read as claiming these are two distinct resources, which isn't quite the intent. In practice, this theoretical objection rarely causes real problems, and URI versioning's practical advantages (visibility, cacheability, zero client tooling required) are why it remains the dominant real-world choice despite the theoretical impurity.

Routing multiple versions to different implementations

app.MapGet("/api/v1/users/{id}", GetUserV1);
app.MapGet("/api/v2/users/{id}", GetUserV2);

At the routing level, this is often the simplest possible implementation — two entirely separate route handlers, potentially sharing underlying business logic but each shaping its own request/response contract independently, which Section 7 covers with more structure via the Asp.Versioning package specifically.

---

4. Header Versioning

Keeping the URI clean, moving the version into a custom header

GET /api/users/42
X-Api-Version: 2

Header versioning keeps the URI stable and semantically focused purely on the resource, moving version negotiation into a request header — theoretically cleaner from a strict REST perspective, since the URI genuinely does identify one consistent resource regardless of version.

The practical costs

❌ Not visible in a browser address bar, or plain URL sharing
❌ Not natively cacheable by URL-keyed HTTP caches/CDNs (the same URL now serves different content per header)
❌ Requires every client to remember to set the header correctly — a missing header means falling back to
   some default version, which itself needs a clear, well-documented policy

The tradeoffs run in the opposite direction from URI versioning's — better theoretical purity, at the cost of discoverability and cacheability that matter quite a lot in practice for public or loosely-governed APIs; header versioning tends to be more common in tightly-controlled internal APIs where every client is known, cooperative, and unlikely to forget the header, than in public APIs serving a broad, less coordinated set of consumers.

---

5. Query String Versioning

The lightest-weight option

GET /api/users/42?api-version=2.0

Query string versioning sits between URI and header versioning in most respects — visible in the URL (better discoverability than headers), but arguably even more clearly signals "this is a query parameter affecting behavior, not part of the resource's identity" than embedding the version in the path segment itself does. It's cacheable by URL, same as URI versioning, since the full query string is typically part of a cache key.

Where this is commonly seen in practice

Many well-known public APIs (including several major cloud providers' own REST APIs) use exactly this pattern — it's a pragmatic, low-ceremony default, and .NET's Asp.Versioning package (Section 7) supports it as one of several interchangeable version-reader strategies, often combined with URI or header versioning as a fallback rather than used in isolation.

---

6. Content Negotiation (Media Type) Versioning

Embedding the version in the Accept header's media type

GET /api/users/42
Accept: application/vnd.myapi.v2+json

This is the most "properly RESTful" approach by strict theoretical standards — the client is negotiating which representation of a resource it wants, using HTTP's own built-in content negotiation mechanism (Accept header), rather than treating version as an out-of-band concern. The version becomes part of the media type itself, which is precisely what Accept headers exist to negotiate.

Why this is the least common choice in practice, despite being theoretically the "purest"

It shares header versioning's discoverability and caching downsides, and adds a further practical cost: constructing and parsing custom vendor media types (application/vnd.myapi.v2+json) is more unfamiliar and more friction-prone for the average API consumer than a version number in a URL or a simple custom header — most real-world APIs, even ones whose maintainers are well aware of REST's theoretical purity arguments, choose a more pragmatic strategy (usually URI versioning) specifically because it's dramatically easier for the actual population of API consumers to use correctly.

The honest, practical conclusion across all four strategies

Public API, broad audience, cacheability matters: URI versioning (most common default)
Internal API, known/cooperative clients, REST purity valued: Header versioning
Lightweight, simple public API: Query string versioning
Strict REST theoretical correctness prioritized above ergonomics: Content negotiation

None of these four is objectively "correct" — this is a genuine trade-off among discoverability, cacheability, theoretical REST purity, and client ergonomics, and the right choice depends on the actual audience and constraints of a specific API, echoing this series' consistent theme of matching the tool to the actual problem rather than a single universally correct answer.

---

7. Implementing Versioning in ASP.NET Core

The Asp.Versioning package

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
    options.ApiVersionReader = ApiVersionReader.Combine(
        new UrlSegmentApiVersionReader(),
        new HeaderApiVersionReader("X-Api-Version"),
        new QueryStringApiVersionReader("api-version"));
})
.AddApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
});

This directly extends this series' ASP.NET Core guide's coverage — ApiVersionReader.Combine supports multiple versioning strategies simultaneously (URI, header, and query string, in this example), letting a client use whichever mechanism it prefers, with a documented precedence order when more than one is present in the same request. AssumeDefaultVersionWhenUnspecified and ReportApiVersions (which adds an api-supported-versions response header listing every version the API currently supports) are both genuinely useful defaults for helping clients discover and gracefully handle version negotiation.

Versioning Minimal API endpoints

var versionSet = app.NewApiVersionSet()
    .HasApiVersion(new ApiVersion(1, 0))
    .HasApiVersion(new ApiVersion(2, 0))
    .ReportApiVersions()
    .Build();

app.MapGet("/api/v{version:apiVersion}/users/{id}", GetUserV1)
   .WithApiVersionSet(versionSet)
   .MapToApiVersion(1, 0);

app.MapGet("/api/v{version:apiVersion}/users/{id}", GetUserV2)
   .WithApiVersionSet(versionSet)
   .MapToApiVersion(2, 0);

This connects directly to this series' Minimal APIs guide's route-group patterns — MapToApiVersion routes a specific version to a specific handler, letting v1 and v2 coexist as genuinely separate endpoint implementations sharing the same underlying route template.

Versioning MVC controllers

[ApiController]
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/users")]
public class UsersV1Controller : ControllerBase
{
    [HttpGet("{id}")]
    public IActionResult Get(int id) => Ok(new { id, name = "Ada Lovelace" });
}

[ApiController]
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/users")]
public class UsersV2Controller : ControllerBase
{
    [HttpGet("{id}")]
    public IActionResult Get(int id) => Ok(new { id, fullName = "Ada Lovelace", email = "[e-mail]" });
}

For applications using MVC controllers (per this series' ASP.NET Core guide's comparison of controllers vs. Minimal APIs), separate controller classes per version — sharing the same route template but decorated with different [ApiVersion] attributes — is the standard pattern, keeping each version's request/response shapes and logic cleanly separated rather than accumulating version-conditional branches inside a single shared controller.

Deprecating a version explicitly

[ApiVersion("1.0", Deprecated = true)]

Marking a version as Deprecated doesn't remove it or change its behavior — it adds deprecation metadata to the api-supported-versions/api-deprecated-versions response headers, giving clients a machine-readable signal (checkable by client tooling, or just visible to a developer inspecting response headers) that this version is on a path toward eventual removal, connecting directly to Section 9's deprecation policy discussion.

---

8. Versioning Strategy Beyond REST

GraphQL: evolve the schema, avoid versioning entirely where possible

type Product {
  id: ID!
  name: String!
  price: Float!
  discountPercent: Int  # NEW field — existing queries that don't request it are completely unaffected
}

As covered in this series' GraphQL guide, GraphQL's client-driven query model means a client only ever receives the specific fields it explicitly requests — adding new fields to a type is inherently, automatically non-breaking for every existing client, since no existing query could possibly have been requesting a field that didn't exist yet. This is precisely why GraphQL APIs typically don't version at the API level the way REST does — the standard practice is evolving one continuously-growing schema, deprecating individual fields (via the @deprecated directive) rather than versioning the entire API:

type Product {
  name: String! @deprecated(reason: "Use displayName instead")
  displayName: String!
}

gRPC: Protocol Buffers' field-number discipline as its own versioning mechanism

As covered in this series' gRPC guide, Protocol Buffers' field-number-based wire format means adding a new field (with a new, never-before-used field number) is automatically, structurally non-breaking for existing clients — old clients simply don't know about and ignore the new field, and old field numbers must never be reused once retired. This is the same additive-change discipline from Section 2, but enforced by the wire format itself rather than by a versioning scheme layered on top — gRPC services do sometimes still version at the service level (OrderServiceV2) for genuinely breaking redesigns, but field-level evolution within a message rarely needs it.

Event-driven contracts: schema compatibility rules, not URL versions

As covered in this series' Kafka guide's Schema Registry discussion and Event-Driven Architecture guide's schema evolution section, an event's schema is versioned via compatibility-checked evolution (backward/forward/full compatibility rules enforced by a schema registry) rather than a URL path segment — the underlying principle is identical to REST's additive-change discipline (Section 2), just enforced through different tooling appropriate to an asynchronous, many-consumer context where there's no single request/response exchange to attach a version header or URL segment to.

The consistent underlying principle across every protocol

Regardless of which specific mechanism a given protocol uses — a URL segment, a field's absence being safely ignorable, a schema registry's compatibility check — the same core discipline from Section 2 underlies all of them: prefer changes that existing clients/consumers can safely ignore, and reserve the heavier, protocol-specific versioning mechanism (a new URI version, a new service definition, a major schema version) for the genuinely breaking changes that discipline can't avoid.

---

9. Deprecation and Sunset Policy

Versioning without a deprecation plan just accumulates versions forever

v1 (2022) — still supported
v2 (2023) — still supported
v3 (2024) — still supported
v4 (2025) — still supported
... every version ever shipped, maintained indefinitely, forever

Introducing a new version without a clear policy for eventually retiring old ones means an API's maintenance burden only ever grows — every supported version needs its own tests, its own bug fixes, and its own consideration in every future change, indefinitely. A genuine versioning strategy needs a paired deprecation and sunset policy from the start, not as an afterthought once the version count has already become unmanageable.

Communicating deprecation via standard HTTP headers

HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Dec 2026 23:59:59 GMT
Link: <https://api.example.com/docs/migration/v1-to-v2>; rel="successor-version"

The Deprecation and Sunset HTTP response headers (both from IETF specifications) give clients a machine-readable, standardized way to detect that the version they're using is scheduled for removal, and by when — pairing this with a Link header pointing to migration documentation gives automated tooling (and attentive developers watching their own logs) a genuine, actionable signal, rather than deprecation being something clients only discover when the version is abruptly removed.

A reasonable deprecation timeline, stated explicitly

1. Announce: new version (v2) ships; v1 marked Deprecated, with a clear Sunset date
2. Grace period: v1 continues working, unchanged, for a defined, communicated window (commonly 6-12+ months
   for external/public APIs; can be shorter for tightly-coordinated internal APIs)
3. Sunset: v1 is actually removed, only after the announced date has passed AND ideally after confirming
   via usage metrics that meaningful traffic has migrated away from it

The specific duration is a business and audience judgment call (a public API with many independent third-party integrators generally needs a considerably longer grace period than an internal API where every consumer is a known, coordinated team) — what matters structurally is that the timeline is explicit, communicated in advance, and genuinely honored, since a broken promise about a sunset date erodes exactly the trust versioning is meant to preserve.

Monitoring actual version usage before sunsetting

# Per this series' Prometheus/Grafana guide — tracking real traffic per API version
sum(rate(http_requests_total{route=~"/api/v1/.*"}[1h]))

As covered in this series' Prometheus/Grafana guide, tracking request volume per API version directly informs whether it's actually safe to sunset a deprecated version — sunsetting based purely on a calendar date, without confirming via real traffic data that meaningful usage has genuinely migrated away, risks breaking clients who never got the deprecation notice or haven't prioritized migrating yet.

---

10. Semantic Versioning vs. API Versioning

Two genuinely different, easily conflated concepts

Semantic Versioning (SemVer): MAJOR.MINOR.PATCH — versions a PACKAGE/LIBRARY's release artifact
API Versioning (this guide):    v1, v2 — versions the CONTRACT/SHAPE of an HTTP API

Semantic Versioning (covered in the context of NuGet packages and npm dependencies) governs how a software package's version number communicates the nature of changes between releases (a MAJOR bump signals a breaking change, MINOR signals additive new functionality, PATCH signals a bug fix) — this is a related but distinct concept from API versioning, which governs the contract of a network-facing API, not a package's release artifact.

Where the two do relate

An API's underlying IMPLEMENTATION might go through SemVer versions 1.4.2, 1.5.0, 1.6.1
  ...while its PUBLIC API CONTRACT stays at v1 throughout that entire span,
  since none of those internal releases introduced a breaking CONTRACT change

An API's server-side implementation can legitimately go through many internal SemVer-style releases (bug fixes, internal refactoring, new non-breaking capabilities) without ever needing a new API contract version — the API contract version (v1, v2) should track breaking changes to what clients depend on, while the implementation's own version history can be considerably more granular and frequent, tracking every deployment regardless of whether it changed the external contract at all.

---

11. Versioning and Client SDKs

Generated or hand-maintained SDKs add another layer to the versioning question

API contract version:  v2
SDK package version (SemVer):  3.4.1  — this specific SDK release targets the v2 API contract

For APIs that provide official client SDKs (auto-generated from an OpenAPI spec, or hand-maintained), the SDK package itself has its own SemVer version, independent of but tracking which API contract version it targets — a breaking API contract change (v1 → v2) typically corresponds to a major SDK version bump, while additive API changes might only need a minor SDK version bump to expose newly-available optional fields or endpoints.

The genuine value of official SDKs in reducing breaking-change pain for clients

An SDK that abstracts the raw HTTP contract behind a typed client library can sometimes absorb minor API changes without requiring every consuming application to update its own code — the SDK's own version bump handles the adaptation internally, and consuming applications only need to update if they want the SDK's newly-exposed capabilities, softening (though not eliminating) the coordination burden a raw, unabstracted HTTP contract change would otherwise impose directly on every client.

---

12. Common Pitfalls

Pitfall	Why it hurts	Better approach
Bumping the version for every minor, genuinely additive change	Trains clients to distrust version numbers; unnecessary migration churn	Reserve version bumps for genuinely breaking changes; rely on additive evolution otherwise
Making a breaking change without any version bump at all	Silently breaks existing, well-behaved clients with no warning	Any genuinely breaking change requires either a new version or an explicit expand/contract migration
No deprecation/sunset policy paired with introducing a new version	Old versions accumulate indefinitely, growing maintenance burden forever	Define and communicate an explicit deprecation timeline from the moment a new version ships
Sunsetting a version purely by calendar date, without checking real usage	Breaks clients who never saw the deprecation notice or haven't migrated yet	Monitor actual per-version traffic before finalizing a sunset
Treating GraphQL or gRPC the same way as REST's URI versioning	Misses each protocol's own, more idiomatic evolution mechanism	Use field-level deprecation (GraphQL) or field-number discipline (gRPC) as the primary tool, per Section 8
No machine-readable deprecation signal (just documentation)	Clients (and their automated tooling) have no way to detect deprecation programmatically	Use the standard Deprecation/Sunset HTTP headers
Conflating SemVer (package version) with API contract version	Confuses two genuinely different, differently-scoped versioning concerns	Keep an API's contract version (v1/v2) distinct from its implementation's or SDK's SemVer version

---

Quick Reference Table

Concept	Purpose
Breaking vs. additive change	The core distinction determining whether versioning is even necessary
Expand/contract	A lighter-weight alternative to a full version bump, for a single field's evolution
URI versioning	/api/v1/... — most common, most discoverable, most cacheable
Header versioning	X-Api-Version — cleaner URIs, weaker discoverability/caching
Query string versioning	?api-version=2.0 — lightweight, visible, cacheable
Content negotiation versioning	Accept: application/vnd.api.v2+json — theoretically purest, least ergonomic
Asp.Versioning	The .NET package implementing all four strategies, combinable
Deprecation/Sunset headers	Standard, machine-readable deprecation signaling
GraphQL field deprecation	The idiomatic GraphQL alternative to REST-style API versioning
gRPC field-number discipline	Protocol Buffers' own structural mechanism for safe, additive evolution
Schema Registry compatibility rules	The event-driven equivalent, enforced for Kafka/messaging contracts

---

Conclusion

API versioning exists to manage one specific, unavoidable tension: an API needs to evolve, and the clients depending on it need stability on their own timeline, not yours. The most effective versioning strategy is, perhaps counterintuitively, the discipline that reduces how often a version bump is actually necessary at all — maximizing additive, backward-compatible changes (new optional fields, new endpoints, widened validation) and reserving genuine version bumps, with their real coordination and migration cost, specifically for changes that are unavoidably breaking.

When a version bump genuinely is necessary, the choice of mechanism (URI, header, query string, or content negotiation for REST; field deprecation for GraphQL; field-number discipline for gRPC; schema compatibility rules for event-driven contracts) matters less than the surrounding discipline: a clear, communicated deprecation and sunset policy, machine-readable signals clients can act on programmatically, and genuine verification via real traffic data before finally retiring what's been deprecated. Get that discipline right, and API versioning becomes exactly what it's meant to be — a safety valve used deliberately and rarely, not a routine, dreaded ritual accompanying every change.

---

Found this useful? Feel free to star the repo, open an issue with corrections, or share the additive change that quietly avoided a version bump nobody wanted to coordinate.