What counts as a breaking change in a microservice API?

A breaking change is any change that can make a correctly written existing client fail or behave differently without that client changing any code. In practice, that covers a short list:

  • Removing or renaming a field, endpoint or enum value.
  • Changing a field's type, such as an integer ID becoming a string.
  • Changing what a field means, such as amount moving from cents to dollars.
  • Tightening validation, so requests that were accepted are now rejected.
  • Changing a default value.
  • Altering error codes, or how pagination behaves (page size, cursor format, ordering).
Change Breaking? Why
Add optional response field No Tolerant readers ignore unknown fields
Add optional request parameter No Old requests keep the old behavior
Rename or remove field Yes Clients reading it get nothing
Stricter validation Yes Previously valid requests now fail
New default value Yes Same request, different result
Different error code Yes Client retry and branching logic misfires

This article's thesis is that the versioning mechanism (URL, header or media type) matters less than two other things. Teams need a shared definition of "breaking," and they need a deprecation policy that is actually enforced.

Version only for breaking changes, and only with a major number. Putting minor or patch numbers in URIs or headers, or cutting a new version on every deploy, creates routes and contracts that differ in nothing a client can act on. You still have to test, document and retire each one.

Additive changes are only safe if consumers really are tolerant readers. A client that deserializes strictly and rejects unknown fields will break when you add one. So will a client that depends on JSON field order or parses error message text. Write that expectation into your API guidelines so consumers know it is required of them.

import json
from dataclasses import dataclass, fields

@dataclass
class Order:
    id: str
    amount_cents: int

before = '{"id": "ord_123", "amount_cents": 4999}'
after = '{"id": "ord_123", "amount_cents": 4999, "currency": "EUR"}'

def strict_reader(body: str) -> Order:
    # Maps every key to a constructor argument, so an unknown key
    # raises TypeError. An additive change breaks this client.
    return Order(**json.loads(body))

def tolerant_reader(body: str) -> Order:
    data = json.loads(body)
    known = {f.name for f in fields(Order)}
    # Keeps only the fields this client understands and ignores the rest.
    # Missing required fields still fail, which is correct: that is a breaking change.
    return Order(**{k: v for k, v in data.items() if k in known})

for name, reader in [("strict", strict_reader), ("tolerant", tolerant_reader)]:
    for label, body in [("before", before), ("after", after)]:
        try:
            print(name, label, reader(body))
        except TypeError as exc:
            print(name, label, "FAILED:", exc)

A strict client that rejects unknown fields fails when the server adds an optional field. A tolerant reader ignores the new field and keeps working without any code change.

Why is API versioning used?

Microservices are deployed independently, so a provider and its consumers are almost never released together. API versioning is used to decouple those release schedules when a breaking change is unavoidable. The provider can ship a new contract while existing clients keep calling the old one, and each consumer migrates when it is ready instead of on the provider's deploy day.

It serves three concrete purposes:

  • Stability for existing clients. A client that worked yesterday keeps working after the provider deploys, because the contract it targets has not changed.
  • A controlled path for breaking changes. Without versioning, a provider facing a breaking change must either coordinate a simultaneous release with every consumer or not make the change at all. Versioning offers a third option: run the old and new contracts side by side for a defined period.
  • An explicit lifecycle. A version number gives deprecation, migration and removal something to attach to. You can say "v1 is deprecated and will be removed on a published date," measure who still calls it, and retire it.

Versioning is not a substitute for careful API design. Most changes should be additive and need no new version at all. Versioning is the mechanism for the remaining cases where a contract must break.

Who should use API versioning?

Explicit versioning is worth its cost when the provider cannot change or coordinate all of its consumers:

  • Teams running public or partner APIs. Consumers are outside your organization, upgrade on their own schedules, and may never upgrade. Explicit major versions are close to mandatory here.
  • Teams whose clients ship as installed software. Mobile apps, desktop clients, device firmware and on-premises installs keep running old builds long after a new release. The server must keep serving the contract those builds expect.
  • Platform teams serving many internal consumers. When dozens of services depend on a shared API and the platform team has no authority to change their code, versioning lets consumers migrate independently.
  • Teams in regulated or contractual environments, where an integration's behavior must not change without notice.

Teams that may not need explicit version numbers are those whose consumers all live in repositories they control, with shared CI and contract tests. For them, additive evolution and expand-and-contract (covered below) usually cost less than maintaining parallel versions.

How does API versioning work with URLs, headers and media types?

Every strategy follows the same basic mechanism. The client puts a version selector somewhere in the request. The server, or a gateway in front of it, reads that selector and dispatches the request to version-specific handling. That handling can be a separate route, an adapter, or a separate deployment. The response is shaped according to the selected version's contract. The strategies differ only in where the selector lives, and that determines which infrastructure (routers, caches, gateways, logs, client generators) can see it.

URL path versioning

The version is part of the resource path: GET /v1/orders/42. Every layer that already understands paths handles it with no extra work. Routers match on the prefix, caches key on the full URL, access logs record the version, and gateway rules can send /v2/* to a separate deployment. You can test it by pasting the URL into a browser or running curl. The downside is that the version becomes part of the resource's identity. /v1/orders/42 and /v2/orders/42 look like two different orders, even though they are the same order.

Custom header versioning

The URI stays stable, and the client selects a version with a header such as API-Version: 2. You must decide what happens when the header is missing. Pick a fixed default, usually the oldest supported version, and document it. If the default follows "latest", an omitted header becomes a silent breaking change. Because the response now depends on a request header, send Vary: API-Version. Without it, a shared cache can serve a v2 body to a v1 client.

Media type versioning

The version lives in a vendor media type in the Accept header, for example Accept: application/vnd.example.order.v2+json. This uses standard HTTP content negotiation, so each resource can version independently. It also lets the server reply 406 Not Acceptable when it can't serve the requested version. The response must include Vary: Accept. This approach has the steepest learning curve: clients need to build correct Accept values, and many tools and engineers never set them.

GET /v1/orders/42 HTTP/1.1
Host: api.example.com

HTTP/1.1 200 OK
Content-Type: application/json
GET /orders/42 HTTP/1.1
Host: api.example.com
API-Version: 2

HTTP/1.1 200 OK
Content-Type: application/json
API-Version: 2
Vary: API-Version
GET /orders/42 HTTP/1.1
Host: api.example.com
Accept: application/vnd.example.order.v2+json

HTTP/1.1 200 OK
Content-Type: application/vnd.example.order.v2+json
Vary: Accept

GET /orders/42 HTTP/1.1
Host: api.example.com
Accept: application/vnd.example.order.v9+json

HTTP/1.1 406 Not Acceptable
Vary: Accept

Side-by-side HTTP requests and responses for path, header and media type versioning, showing where the version goes and which Vary header each strategy needs.

Which API versioning strategy has the fewest trade-offs?

No strategy is free. Each one moves the cost to a different place.

Concern URL path Custom header Media type
Visibility and debuggability Shows up in logs, browsers and curl history Hidden unless headers are logged Hidden, and the Accept string is verbose
Cache and CDN behavior Works by default, since each URI is its own cache key Needs Vary on the header Needs Vary: Accept
Gateway routing Simple prefix match Header-match rules Parsing Accept values
Tooling and generated clients Broad support Usually supported Often awkward
Granularity Whole API Whole API or per resource Per resource
Typical failure mode Big-bang client upgrades Silent fallback when the header is stripped Untested version combinations

URL versioning is easy to operate, but it breaks the idea that a URI identifies a resource. /v1/orders/42 and /v2/orders/42 look like two different orders. Links stored by clients also carry the old version. Because the version covers the whole API, a client moves everything at once, which makes upgrades large and get postponed.

Header and media type versioning fail silently. If a proxy strips the header, the request still succeeds, just against the default version. If Vary is missing, a cache can serve a v2 body to a v1 client. Per-resource media types add a further risk: a client can combine order v3 with customer v1, a pairing nobody tested.

All three strategies share the default-version trap, which applies to requests that arrive with no version:

  • Pinning them to the oldest version keeps unversioned clients working, but you can never remove that version, because you cannot tell who depends on it.
  • Floating them to the latest version breaks every unpinned client on each release.

Neither default is safe. The practical fix is to require a version on every request and reject requests that lack one.

Do internal APIs need version numbers at all?

Public APIs need versions because the provider cannot see or coordinate with most of its consumers. Internal APIs often can. If every caller lives in repositories your organization controls, you can find them, change them, and confirm they still work. That makes it possible to evolve a single contract in place instead of maintaining several.

Three practices together replace most explicit versions:

  • Consumer-driven contract tests. Each consumer publishes the requests it sends and the fields it reads. The provider's CI checks every change against those contracts, so a breaking change fails the build before it ships.
  • Expand-and-contract (parallel change). Add the new shape first, migrate consumers, then remove the old shape. The contract never breaks in a single step.
  • Tolerant readers. Clients ignore fields they don't recognize and read only what they need. This lets the provider add fields freely.

To rename customer_name to full_name:

  1. Expand. Return both fields with the same value, and accept either one on writes.
  2. Migrate. Update consumers to use full_name, and track remaining reads of customer_name through contract tests or request logs.
  3. Contract. Once nothing reads customer_name, stop sending it and stop accepting it.

This approach suits teams with a service catalog, shared CI, and the authority to change their consumers. Avoid it when you cannot list every consumer, when some consumers cannot be changed (mobile apps, partner integrations, vendored binaries), or when clients use strict deserializers that reject unknown fields. In those cases, keep explicit versions.

// Expand phase of renaming customer_name -> full_name.
// Old and new consumers both keep working while they migrate.

interface CustomerRecord {
  id: string;
  fullName: string; // internal model already uses the new name
}

// Response: send both fields with the same value.
export function toResponse(c: CustomerRecord) {
  return {
    id: c.id,
    full_name: c.fullName,
    customer_name: c.fullName, // DEPRECATED: remove in the contract step
  };
}

// Write: accept either field, prefer the new one.
export function fromRequest(body: {
  id: string;
  full_name?: string;
  customer_name?: string; // DEPRECATED
}): CustomerRecord {
  const name = body.full_name ?? body.customer_name;
  if (name === undefined) {
    throw new Error("full_name is required");
  }
  if (body.full_name === undefined) {
    // Record legacy writers so you know when the contract step is safe.
    console.warn(`legacy field customer_name used for customer ${body.id}`);
  }
  return { id: body.id, fullName: name };
}

// Contract step (later): delete customer_name from toResponse and
// fromRequest once contract tests and logs show no remaining users.

During the expand step, a provider returns both the old and new field names and accepts either one on writes. It logs requests that still use the legacy name, so you know when it is safe to remove it.

How do you run multiple API versions without forking the codebase?

The goal is to keep one implementation of the business logic and push version differences to the edges of the system.

Adapter layer over a single domain model

The most maintainable pattern is a thin translation layer per version. Each adapter converts an incoming v1 or v2 request into the current internal command, calls the shared domain service, and maps the result back to that version's response shape. The request path looks like edge gateway → v1 adapter | v2 adapter → domain service. Bug fixes and business rules land once, in the domain service, and every version receives them. Adapters stay small because they only rename fields, fill defaults, and reshape payloads.

The risk appears when the new model cannot represent old behavior. Suppose v1 accepted a single free-text address and v2 requires structured fields. The v1 adapter must parse, guess, or reject, and each of those choices changes what v1 means. Information can also be lost going outward: if the domain model drops a field, the v1 adapter has nothing to return, so it fabricates a value. When an adapter starts carrying business rules, record that fact and treat the old version as a deprecation candidate.

Gateway routing to separate deployments

If behavior has diverged too far for an adapter to bridge, route by version at the gateway to separate deployments. Use this as a short-lived migration bridge, not as the default. Forking the whole codebase per version duplicates every security patch, schema migration, and on-call surface, and that cost grows with each version you keep running.

// edge gateway --/v1/*--> v1 adapter --\
//              --/v2/*--> v2 adapter ----> OrderService (one domain model)

type Address = { street: string; city: string; postalCode: string };
interface CreateOrder { customerId: string; shipTo: Address; currency: string }
interface Order { id: string; shipTo: Address; status: "pending" | "shipped" }
interface OrderService { create(cmd: CreateOrder): Promise<Order> }

// v1 wire shape: one free-text address and no currency field.
type V1CreateRequest = { customer_id: string; address: string };
type V1OrderResponse = { order_id: string; address: string; state: string };

export function makeV1Adapter(orders: OrderService) {
  return async (req: V1CreateRequest): Promise<V1OrderResponse> => {
    // Lossy inbound mapping: free text must become structured fields.
    // Reject instead of guessing, so the change to v1 semantics is visible, not silent.
    const parts = req.address.split(",").map((p) => p.trim());
    if (parts.length !== 3 || parts.some((p) => p === "")) {
      throw new Error("422: v1 address must be 'street, city, postal code'");
    }
    const [street, city, postalCode] = parts;

    // Business rules live only in the domain service; the adapter just reshapes.
    const order = await orders.create({
      customerId: req.customer_id,
      shipTo: { street, city, postalCode },
      currency: "USD", // default that v1 clients never sent: document it as v1 behavior
    });

    // Outbound mapping: flatten the structured address back into v1's single string.
    return {
      order_id: order.id,
      address: `${order.shipTo.street}, ${order.shipTo.city}, ${order.shipTo.postalCode}`,
      state: order.status,
    };
  };
}

A v1 adapter in front of a single OrderService that renames fields, fills a default, and rejects free-text addresses it cannot map to the structured v2 model rather than guessing.

How should a deprecation policy work in practice?

A deprecation policy is a contract with dates, signals, and exit criteria. Publish the deprecation date and the earliest removal date together, so consumers can plan the migration as scheduled work.

Signal deprecation inside the responses. A Deprecation header marks the version as deprecated, and a Sunset header carries the planned removal date. A Link header can point to the migration guide. For example, a v1 response might carry Sunset: Sat, 01 Aug 2026 00:00:00 GMT next to its normal payload. Engineers rarely read changelogs, but clients, gateways, and logging tools can detect headers and raise alerts.

The policy fails without consumer identification. If requests arrive anonymously, a hypothetical observation such as "v1 still gets 2% of traffic" tells you nothing about whom to contact. You will either break someone unexpectedly or never remove the version. Require an API key, mTLS identity, or service-name header, and break down old-version traffic by consumer.

Policy checklist

  • Announce deprecation and removal dates in docs and in response headers.
  • Identify every caller and track per-consumer traffic on deprecated versions.
  • Contact each remaining consumer directly as the removal date approaches.
  • Remove only when the date has passed and traffic is zero or explicitly waived.

Removal should be gated on observed usage, not on the calendar alone, because each surviving version multiplies testing, documentation, monitoring, and security patching. Illustrative estimate, assumed inputs: if each live version adds 4 engineer-hours per security patch and you ship 12 patches a year, keeping three versions instead of one costs roughly 96 extra hours annually, before counting test matrices or dashboards.

How does API versioning affect development cost?

Versioning moves cost around more than it removes it. The provider pays to keep the old contract alive so consumers don't have to migrate on the provider's schedule. The main cost drivers are:

  • Implementation. Each live version needs routing plus an adapter or a separate deployment. Adapters over one domain model keep this cost small. Forked codebases make it grow with every change.
  • Testing. Every version needs its own contract and regression tests. With per-resource media types, the matrix includes combinations of resource versions, not just a list of versions.
  • Documentation and client generation. Each major version needs its own spec, reference docs, examples, and generated SDKs, and all of them have to be kept accurate.
  • Operations. Dashboards, alerts, and per-version traffic metrics are needed to know when a version can be removed. On-call engineers must understand every version that is still running.
  • Security and dependency maintenance. Patches have to be applied and verified across every version. This is the cost that most often keeps growing quietly.
  • Migration on the consumer side. Each new major version gives every consumer migration work. Whole-API URL versions concentrate that work into large upgrades.

The strategy choice affects where cost appears. URL versioning is cheap to operate and debug, but it encourages whole-API version bumps. Header and media type versioning avoid new routes, but they add cost in cache configuration, gateway rules, and debugging silent fallbacks.

Illustrative estimate, assumed inputs: assume an adapter for an old version takes 3 engineer-days to build and 1 engineer-day per quarter to keep in sync with domain changes. Running it for two years costs about 3 + 8 = 11 engineer-days on the provider side. Now assume 10 consumers would otherwise each spend 2 engineer-days on a coordinated, same-day migration, plus the coordination overhead. Under these assumptions the old version roughly pays for itself in avoided consumer effort and release risk. If it stays alive for six years instead of two, the balance shifts against it. This is why the removal date matters as much as the versioning mechanism.

The largest lever on cost is how often you create a new major version. Additive evolution, tolerant readers, and contract tests keep that number low. Few versions mean little parallel maintenance, whichever mechanism you choose.

What are the alternatives to API versioning?

Explicit version numbers are one way to handle contract change. Several alternatives avoid or postpone them:

  • Additive-only evolution. Never remove or change existing fields; only add optional ones. Combined with tolerant readers, this makes most changes non-breaking. It fails when a field's meaning genuinely has to change, or when old fields pile up with no way to remove them.
  • Expand-and-contract with contract tests. As described above, the contract moves through a series of compatible states instead of breaking in one step. This works best when you can see and change every consumer.
  • New resources or endpoints instead of new versions. If an operation's behavior must change, introduce a new resource name (for example, a new endpoint for the redesigned flow) alongside the old one, and deprecate the old one individually. This limits the breaking change to the affected operation instead of the whole API.
  • Field-level deprecation. Mark individual fields as deprecated in the schema and documentation, track who reads them, and remove them one at a time. This is version-free in the same way expand-and-contract is.
  • Per-client pinning with server-side translation. Each client, or each API key, is pinned to the contract it integrated against, often identified by a release date. The server translates responses into that contract through a chain of transformations. This spares clients from choosing versions, but the server has to maintain the transformation chain.
  • Coordinated lockstep deployment. Release the provider and all its consumers together. This is only realistic for a small number of tightly coupled services owned by one team, and it gives up the independent deployability that microservices are meant to provide.

Each alternative trades version management for some other discipline: strict additive rules, consumer visibility, or server-side translation. Choose the one whose discipline your organization can enforce.

When should you choose each API versioning strategy?

The cost of parallel versions points to a default: expose URL major versions (/v1/, /v2/) at the public edge, and evolve internal APIs additively behind consumer-driven contract tests. The table below shows when to deviate from that default.

Situation Prefer Avoid
Public or partner API URL major version Media type versioning, because many consumers never set custom Accept values correctly
Internal service-to-service Additive changes plus contract tests, with no version number Per-team URL versions that multiply routes nobody retires
Gateway-heavy routing URL version, because path-based routing rules are simple to audit Header versioning when the gateway's header matching is inconsistent across environments
Heavy CDN caching URL version, because each version gets a distinct cache key Header or media type versioning unless every cache honours Vary
Generated clients URL version with one spec per major version Media type versioning, which generators often handle less uniformly than paths

Header versioning is a reasonable choice when you control every client and every intermediary, such as a mobile app talking to its own backend. It needs no new routes and leaves URLs stable. Media type versioning fits APIs that version individual resource representations rather than the whole surface, but the clients have to be disciplined.

This default saves engineering time in three ways:

  • Fewer parallel versions: additive evolution means a new major version is rare, so patch and test effort stays close to one version's worth.
  • Less coordination: contract tests replace meetings. A provider learns it would break a consumer from CI, not from an incident.
  • Routine retirement: with few majors, each with a published deprecation date and traffic metrics, removing one becomes a scheduled ticket rather than a cross-team project.

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 api versioning strategies, 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 shared variable is one edit and one review instead of editing every service's .env by hand.

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.
  • A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
  • 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.