What counts as a breaking change in microservice API versioning?
Microservice API versioning is the practice of managing how a service's contract changes over time while existing consumers keep working. The /v2 in a URL is only a label. What matters is whether a change forces consumers to change their code, and that depends on what they actually do with your responses.
| Change | Usually safe? | Why it can still break |
|---|---|---|
| Add optional request field | Yes | Rarely breaks |
| Add response field | Yes | Strict deserializers reject unknown fields |
| Add endpoint | Yes | Rarely breaks |
| Add enum value | Looks safe | Exhaustive switch statements fail or misroute |
| Remove or rename field | No | Consumers read a missing value |
| Change field type (int → string) | No | Parsing fails |
| Tighten validation | No | Previously valid requests now get 4xx |
| Change a default | No | Same request, different behavior |
| Change error codes or semantics | No | Retry and fallback logic misfires |
| Change pagination or sort order | Looks safe | Clients that dedupe by position or stop at "last seen ID" skip or repeat records |
The rows marked "looks safe" cause most surprises. Adding an enum value doesn't change the schema shape, but a consumer that maps status to a closed set of cases will crash or drop the record. Switching from offset to cursor pagination, or returning results in a different default order, leaves every field intact while changing behavior that clients relied on without documenting it.
So "non-breaking" is a claim about consumer behavior, not about schemas. Before calling a change compatible, check how consumers deserialize, branch on values, and iterate collections. Contract tests that consumers own are the most direct way to find out.
How does microservice API versioning work?
Versioning is a small set of mechanisms that together let a provider change its contract without changing every consumer at the same moment.
- The contract is written down and carries a version. The service publishes a machine-readable contract, such as an OpenAPI document or a Protocol Buffers schema, and each major version of that contract has its own identifier:
v1,v2, and so on. Within a major version, only backward-compatible changes are allowed. A breaking change requires a new major version. - The client selects a version on every request. The selector lives in the URL path, a header, or a query parameter. The choice of selector affects routing, caching, and logging, as covered below.
- The gateway or service resolves the selector. It reads the selector, checks it against the list of supported versions, and applies a documented rule when the selector is missing or names a retired version, for example by returning
400. - A version-specific layer maps the request. Either an adapter translates the request into the current internal domain model, or the gateway routes it to a deployment that implements that version. Business logic runs and produces a result.
- The response is shaped for the requested version. The result is serialized in the shape that version promises. Headers such as
Vary,Deprecation, andSunsettell caches and clients how to treat it. - Versions move through a lifecycle. A version is introduced, runs in parallel with its predecessor while consumers migrate, is deprecated with a published end date, and is removed. Telemetry tagged with the version shows when it is safe to move to the next stage.
The rest of this article covers each of these pieces: what forces a new version, how to avoid needing one, how to select it, how to serve several at once, how to keep them consistent, and how to retire them.
How do you keep APIs backward compatible so you rarely need a new version?
The cheapest version is the one you never ship. Evolving a single contract additively should be the default, because every new version adds routing, testing, and documentation work that lasts until the old version is retired. Teams with many internal consumers benefit most. A provider that can add a field without coordinating twenty client upgrades keeps shipping independently, which is the reason to run microservices in the first place.
A few design rules make additive evolution safe:
- Tolerant readers. Clients ignore fields they don't recognize instead of failing deserialization. Strict "reject unknown properties" settings turn every provider addition into a breaking change.
- Never reuse names or field numbers. When you remove a field, retire its identifier permanently. In Protocol Buffers, mark the number and name
reservedso the compiler rejects reuse. Otherwise an old client may decode new data into the wrong meaning without any error. - Optional by default. New request fields need a server-side default. New response fields must not be required for a client to function.
- Enums with an unknown fallback. Define an explicit value such as
STATUS_UNSPECIFIED, or map unrecognized strings toUNKNOWN. Make sure every clientswitchhas a default branch that degrades safely rather than throwing.
The example that follows shows a removed field held as reserved and a client that maps an unrecognized enum value to a fallback.
Tolerance has a cost: it can hide real mismatches. If the provider adds requires_manual_review: true, an older consumer drops it without complaint and auto-approves the order. Any field that changes required behavior is semantically breaking, even when the schema change is additive. Treat it as a breaking change.
// order.proto (provider schema, shown for reference)
// syntax = "proto3";
// enum OrderStatus {
// ORDER_STATUS_UNSPECIFIED = 0; // default and fallback value
// ORDER_STATUS_PENDING = 1;
// ORDER_STATUS_SHIPPED = 2;
// }
// message Order {
// reserved 3; // was discount_code; number is never reused
// reserved "discount_code"; // the name is retired too
// string id = 1;
// OrderStatus status = 2;
// optional string gift_note = 4; // additive and optional
// }
type OrderStatus = "ORDER_STATUS_PENDING" | "ORDER_STATUS_SHIPPED" | "UNKNOWN";
const KNOWN = new Set<string>(["ORDER_STATUS_PENDING", "ORDER_STATUS_SHIPPED"]);
interface Order { id: string; status: OrderStatus; giftNote?: string }
// Tolerant reader: copy only the fields this client uses, ignore everything else.
function parseOrder(raw: Record<string, unknown>): Order {
const s = raw.status;
const status = typeof s === "string" && KNOWN.has(s) ? (s as OrderStatus) : "UNKNOWN";
const giftNote = typeof raw.giftNote === "string" ? raw.giftNote : undefined;
return { id: String(raw.id), status, giftNote };
}
function label(order: Order): string {
switch (order.status) {
case "ORDER_STATUS_PENDING": return "Awaiting shipment";
case "ORDER_STATUS_SHIPPED": return "On its way";
default: return "Status unavailable"; // degrade safely, never throw
}
}
// The provider later added ORDER_STATUS_RETURNED and a carrier field.
// This older client still parses the order and renders a safe fallback.
console.log(label(parseOrder({ id: "ord_123", status: "ORDER_STATUS_RETURNED", carrier: "ups" })));
A Protocol Buffers schema retires a removed field with reserved, and a TypeScript client ignores unknown fields and maps an unrecognized enum value to a safe UNKNOWN fallback.
Should you use URL path, header versioning, or query parameters?
The version selector decides how the rest of your HTTP infrastructure sees the request. Gateways, caches, and log pipelines all handle the path well, and many of them ignore headers unless you configure them to look.
| Concern | URL path (/v2/orders) |
Header (custom or Accept media-type parameter) |
Query (?version=2) |
|---|---|---|---|
| Routing | Prefix match at any proxy | Needs header-aware rules | Needs query-aware rules |
| HTTP caching | Separate URLs, no extra work | Requires Vary |
Separate cache keys, but some caches drop or reorder query strings |
| Logging | Visible in every access log | Missing unless you log the header | Usually visible |
| Browser testing | Paste the URL | Needs a client that sets headers | Paste the URL |
| Client ergonomics | Base URL change per version | Version per request, URLs stay stable | Easy to forget, easy to strip |
Header versioning has two failure modes. The first is caching. A client sends GET /orders/42 with Accept: application/vnd.shop.order+json; version=2. The server must answer with Vary: Accept alongside the v2 body. If Vary is missing, a shared cache can serve that v2 body to a v1 client that requested the same URL. The second is a missing header. Decide whether the server defaults to the oldest supported version, defaults to the newest, or rejects the request with 400. Write that rule down. Defaulting to the newest version breaks silent clients every time you release.
Path versioning has a different cost. A version that lives in the base URL tends to cover everything under it. When only /orders changes, teams still publish all of /v2 and make every consumer migrate. You can version individual resources in the path, but most teams don't, because a single API-wide prefix is the easiest pattern to follow.
GET /orders/42 HTTP/1.1
Host: api.example.com
Accept: application/vnd.shop.order+json; version=2
HTTP/1.1 200 OK
Content-Type: application/vnd.shop.order+json; version=2
Vary: Accept
Cache-Control: public, max-age=60
{"id": "42", "status": "shipped", "total": {"amount": "19.99", "currency": "EUR"}}
GET /orders/42 HTTP/1.1
Host: api.example.com
Accept: application/json
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Vary: Accept
Cache-Control: no-store
{"type": "about:blank", "title": "API version required", "detail": "Send Accept: application/vnd.shop.order+json; version=1 or version=2"}
A header-versioned exchange where the server sets Vary: Accept on every response and rejects a request that omits the version, following one written rule for missing headers.
How does running two contract versions side by side work?
There are two ways to serve /v1 and /v2 at the same time. In the first, one service owns the current domain model, and a thin adapter layer translates old requests into it and translates responses back out. In the second, each version runs as its own deployment, and the gateway routes traffic by version.
┌──────────── API gateway ────────────┐
/v1/... ──►│ │
/v2/... ──►│ route by path or version header │
└──────┬───────────────────────┬───────┘
│ v1 │ v2
▼ │
┌─────────────────┐ │
│ v1 adapter │ │
│ map req / resp │ │
└────────┬────────┘ │
▼ ▼
┌──────────────────────────────────────┐
│ current domain model + handlers │
└──────────────────┬───────────────────┘
▼
single datastore
Adapters fit shape changes: renamed fields, restructured payloads, split resources. The logic runs once, so a bug fix applies to every version. The risk is gradual. Someone needs v1 to behave slightly differently, the conditional goes into the adapter, and a year later the adapter is an unowned second implementation that nobody tests as a product.
Separate deployments fit major behavioral or storage changes, where a defect in the new path must not touch existing consumers. That isolation has costs. You run duplicate infrastructure, you apply every bug fix twice, and any migration of shared data has to keep both versions correct while it is in progress.
| Concern | Adapter layer | Separate deployments |
|---|---|---|
| Best for | Shape changes | Behavioral or storage changes |
| Bug fixes | Applied once | Applied per version |
| Risk isolation | Low | High |
| Main failure mode | Logic creeps into adapter | Data migrations and drift |
A: one service + adapter layer B: one deployment per version
/v1 /v2 /v1 /v2
│ │ │ │
▼ ▼ ▼ ▼
┌────────────────────┐ ┌──────────────────────┐
│ API gateway │ │ API gateway │
└──┬──────────────┬──┘ └──┬────────────────┬──┘
│ v1 │ v2 │ v1 │ v2
▼ │ ▼ ▼
┌─────────────┐ │ ┌─────────┐ ┌─────────┐
│ v1 adapter │ │ │ v1 svc │ │ v2 svc │
│ map req/resp│ │ │ v1 model│ │ v2 model│
└──────┬──────┘ │ └────┬────┘ └────┬────┘
▼ ▼ ▼ ▼
┌────────────────────┐ ┌──────────────────────────┐
│ current domain │ │ shared datastore │
│ model + handlers │ │ migrations must keep v1 │
└─────────┬──────────┘ │ and v2 correct in flight │
▼ └──────────────────────────┘
┌──────────────┐
│ datastore │
└──────────────┘
Left: the gateway sends v1 traffic through an adapter onto one current domain model, so logic and fixes exist once; right: the gateway routes each version to its own deployment, which isolates risk but duplicates code paths and forces any migration of shared data to keep both versions correct.
How do you stop parallel API versions from drifting apart?
Drift usually starts when a fix lands in one version's handler and nobody remembers the other. The structural defense is to keep one internal domain model and one implementation of business logic. Each supported version gets a thin adapter at the edge that translates the request into the internal model and the internal result back into that version's response shape. When a bug fix or rule change touches only the core, every version picks it up at once. If an adapter starts making decisions instead of just mapping fields, treat that as a review red flag, because that is where the versions begin to diverge.
Adapters still need proof that each contract holds. Run a contract suite for every supported version in CI, against the same build artifact. A build matrix works well here. Each matrix entry targets one version, for example v1 and v2, and runs that version's suite. The build fails if any entry fails. Adding a version adds an entry, and retiring one removes it. This makes the support burden visible in the pipeline itself.
Provider-side tests only check what you think consumers need. Consumer-driven contract testing reverses that. Each consuming team publishes the requests it sends and the fields it actually reads, and your CI verifies the provider against those expectations. You learn that nobody reads legacy_status on v1 before you remove it. You also learn when someone still does. These breaks surface as a failed check before deploy. Without that check, you would find them through an incident, a rollback, and a cross-team debugging session.
name: contract-tests
on: [pull_request]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: make build # produces dist/orders-service
- uses: actions/upload-artifact@v4
with:
name: service-build
path: dist/
contracts:
needs: build
runs-on: ubuntu-latest
strategy:
fail-fast: false # report every broken version, not just the first
matrix:
api_version: [v1, v2] # add a version = add an entry; retire = remove it
steps:
- uses: actions/checkout@v4
- uses: actions/download-artifact@v4
with:
name: service-build
path: dist/
# Provider-side suite: the contract we believe this version promises.
- name: Provider contract suite (${{ matrix.api_version }})
run: ./scripts/run-contract-suite.sh --version ${{ matrix.api_version }}
# Consumer-driven check: replay expectations published by consuming teams
# (requests they send, fields they read) against this same build.
- name: Verify consumer expectations (${{ matrix.api_version }})
run: ./scripts/verify-consumer-contracts.sh --version ${{ matrix.api_version }}
An illustrative GitHub Actions matrix that builds the service once, then runs the provider contract suite and the consumer-published expectations for each supported API version against that same artifact. Any failing version fails the build.
What does a working deprecation strategy look like?
Deprecation works as a fixed sequence with a published end date. Announce the retirement and the replacement version together. Mark the old operations deprecated: true in the OpenAPI spec so generated clients and linters warn at build time. Then add headers to every response from the old version, so consumers see the change at runtime as well. For example, send Deprecation: true and Sunset: Fri, 30 Apr 2027 23:59:59 GMT, plus a Link header pointing to the migration guide.
Headers only work if someone reads them, so measurement carries the strategy. Tag every request's metrics, logs, and traces with the requested version and an authenticated client identity. A counter such as http_requests_total{api_version="v1", client_id="billing-worker"} combined with a span attribute like api.version=v1 shows exactly who still calls the old contract and how often. Take client identity from a bounded set, such as service accounts or API keys, rather than raw IPs. This keeps metric cardinality under control.
With that data, notify each remaining consumer's owner directly instead of relying on a changelog. Before the sunset date, run scheduled brownouts: short, announced windows where the old version returns errors. Brownouts surface hidden callers while there is still time to fix them. Remove the version on the published date.
Deadlines usually slip for organizational reasons. One critical internal consumer can't migrate, nobody owns that service, and nobody will accept the risk of breaking it. Assign a named owner for every consumer before announcing the sunset. Any extension should be time-boxed and approved by that owner, not granted by default.
When should you avoid parallel versions, and what do they cost?
Run parallel major versions only as a deliberate, time-boxed exception: a breaking change you cannot avoid, for consumers you cannot upgrade on your own schedule. Avoid them in three cases. If the change can be additive, make it additive. If every consumer is internal and can ship in the same release window, migrate them together. If a third version is about to go live, fix the process first, because three live versions usually means old versions are not being retired.
Each supported version adds work that grows with the version count.
Illustrative estimate (assumed numbers, not a benchmark). Assume each version needs 40 contract tests, 6 documentation pages, and 12 alerts.
Maintained surface = V × (tests + doc pages + alerts) = V × (40 + 6 + 12)
With one version, that is 58 items. With three versions, it is 174 items to keep passing, accurate, and covered by on-call. Substitute your own counts.
| Approach | Use when | Main cost |
|---|---|---|
| Additive evolution | New optional fields or new endpoints | Consumers must ignore unknown fields |
| Expand and contract | Renames or type changes | Several deploys and temporary dual reads or writes |
| Coordinated consumer upgrade | A few internal consumers with clear owners | Release coordination across teams |
| Parallel major versions | An unavoidable break with external consumers | The multiplied surface above |
Events and messaging
The same reasoning applies to events, with one extra constraint. A message in a durable log or queue may be replayed months after you change the schema. The old version therefore lives on in stored data, not only in running clients.
Set evolution rules for both sides:
- Producers add only optional fields with defaults. They never reuse, rename, or retype a field.
- Consumers tolerate unknown fields and missing optional fields.
In CI, check compatibility against the oldest schema still in retention, not only against the previous schema.
What are the alternatives to running versioned APIs?
Explicit major versions are one option among several. The alternatives below avoid a second live contract, and each moves the cost somewhere else.
- Additive-only evolution with no version numbers. The contract never breaks, so there is only ever one version. This works when the provider controls its own discipline: tolerant readers, retired field identifiers, optional new fields. The cost is that some designs can never be fixed, only added alongside, so old fields accumulate.
- Expand and contract (parallel change). For a rename or type change, add the new field next to the old one, write both, migrate consumers to read the new field, confirm through telemetry and consumer contracts that nobody reads the old one, then remove it. No new version is published, but the change takes several deploys and a period of dual writes.
- Coordinated upgrade. When all consumers are internal and have owners, change the provider and every consumer together. This is the cheapest option for a small number of consumers and the most expensive one once release coordination spans many teams.
- A new resource or operation instead of a new version. If only one endpoint needs a breaking change, add a new endpoint with the new shape and deprecate the old endpoint alone. Consumers that never call it don't migrate at all, which avoids the "all of
/v2" problem described for path versioning. - Field-level deprecation in schema-driven APIs. GraphQL APIs typically evolve one schema and mark individual fields with the
@deprecateddirective, relying on clients requesting only the fields they use. Protocol Buffers APIs follow a similar pattern with optional fields andreservedidentifiers. Both still need usage telemetry to know when a field can be removed. - Consumer opt-in to new behavior. For behavioral changes, let clients request the new behavior explicitly, through a request parameter or a capability flag, while the default stays the same. This works for a limited number of changes. Each flag is a branch you must test and eventually remove.
In practice, most teams combine these: additive evolution and expand-and-contract by default, a new resource for isolated breaks, and a parallel major version only for broad breaking changes with external consumers.
How can API versioning save engineering time?
Versioning adds maintenance work, so its time savings come from avoiding more expensive work elsewhere. The savings are real only when the practices above are in place.
- Independent releases. With additive evolution and a stable contract, a provider ships without waiting for consumer teams, and consumers upgrade on their own schedules. The alternative is lockstep releases, where one change blocks on the slowest team.
- Breaks found before deploy instead of in production. Consumer-driven contract tests in the version matrix turn a breaking change into a failed CI check that one engineer fixes. Without them, the same break shows up as an incident that involves on-call, a rollback, and debugging across teams.
- Fix once. With one domain model and thin adapters, a bug fix or business-rule change lands in one place and reaches every supported version. Teams that let versions fork into separate handlers pay for every fix twice and for the investigation when they diverge.
- Migration planning from data, not guesswork. Version and client tags on metrics show exactly which consumers still call an old version. That replaces broad announcements and manual audits with direct conversations with a known list of owners, and brownouts surface hidden callers on a planned date rather than during an outage.
- Retiring versions on schedule. A published sunset date and named consumer owners keep the number of live versions low, which keeps the maintained surface from the earlier estimate small.
Illustrative estimate (assumed numbers, not a measured result). Assume a breaking change affects 8 consuming teams. If it ships without versioning and breaks them in production, assume each team spends 6 hours on diagnosis, an emergency fix, and redeploy: 8 × 6 = 48 engineer-hours, plus provider on-call time and the incident itself. If the change ships as a new version with a deprecation window, assume each team spends 3 hours migrating during normal planned work: 8 × 3 = 24 engineer-hours, with no incident. Against that, count the cost of running both versions in parallel for the deprecation window. Substitute your own team count and hours. The comparison favors versioning when consumers are many or external, and favors a coordinated upgrade when they are few and internal.
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to microservice api versioning, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Changing a route's URL or method automatically notifies the services that consume it — no hunting through repos for callers.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- Consumers learn about a breaking change at review time rather than from production errors.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.