What Is API Versioning? 7 Things Every Developer Should Know (With Examples)

November 8, 2026 · Web Development

Rename one field in a response, and somewhere a client you have never met breaks at 2 a.m. That is the problem API versioning solves. So what is API versioning? It is the practice of publishing an API in identified, parallel editions, so you can change the contract without forcing every existing client to migrate on your schedule. This guide covers it in 7 parts: the contract, breaking vs non-breaking changes, the four strategies, date-based versioning, semantic vs date-based numbering, a verified demo, and how to retire a version.

What is API versioning?

An API is a contract: the endpoints, the request and response shapes, the status codes, the authentication rules, and the documented behaviour. A client is any program that calls it — and the hard part is that you do not control your clients. They integrated months ago and expect the API to behave as it did the day they wrote against it. Versioning is how an API changes without breaking the applications already depending on it: each edition is labelled, older editions keep working, and clients move when ready.

freeCodeCamp puts it plainly: API versioning is the practice of transparently managing changes to your API — old and new behaviour run side by side instead of one silently replacing the other. A version is not a software release: you can deploy backend changes daily without changing the externally supported contract. The version changes only when the contract changes.

Illustration of API versioning: a server connected to a phone app by two parallel lines, one tagged v1 and the other v2, showing two versions of one API running side by side
One API, two promises: v1 and v2 run side by side, and each client keeps the behaviour it built against.

Breaking vs non-breaking changes — the rule that decides everything

First, the distinction every versioning decision hangs on: a breaking change is any change that can make a correctly written client fail or behave wrongly. GitHub's API versions documentation lists them: removing or renaming an operation, parameter, or response field; adding a required parameter; making an optional parameter required; changing a field's type; removing enum values; adding a validation rule; or changing authentication requirements. If your change is on that list, it needs a new version — there is no shortcut.

Everything else is additive, and additive changes should never need a new version. Adding an operation, an optional parameter or header, a response field, or new enum values cannot break a client that ignores what it does not know. That is the first line of defence: most changes should be additive, and a new version the exception. Kubernetes states the same rule first in its deprecation policy: "Once an API element has been added to an API group at a particular version, it can not be removed from that version or have its behavior significantly changed, regardless of track."

Illustration of a breaking change: a puzzle piece being swapped for a differently shaped piece, with a shield guarding a phone app that keeps working
A breaking change swaps a piece of the contract. Additive changes add a piece — nothing already built has to move.

The four strategies: URI, header, query string, and media type

Every versioning scheme answers one question: where does the version identifier live? There are four common answers.

  • URI path versioning puts the version in the address: /v1/invoices and /v2/invoices are separate addresses for separate contracts. It is the most common approach — visible, easy to test, easy to cache, and obvious in logs. The cost: the version becomes part of the resource's identity, so the same invoice lives at two URLs.
  • Header versioning keeps one address and sends the version in a request header, such as X-Api-Version: 2 (GitHub) or Stripe-Version: 2024-06-20 (Stripe). URLs stay clean and stable, but the version is invisible in the address bar, harder to share in a bug report, and caches must vary on the header.
  • Query string versioning appends it to the URL, like /invoices?version=2. It is easy to try, but it clutters the URL and can leak into analytics and logs. Our query string guide covers how those parameters are parsed.
  • Media type versioning (content negotiation) puts the version in the Accept header, such as application/vnd.example.v2+json. It is the purest REST answer — one URL, one resource — but it is obscure, tooling-unfriendly, and hidden from everyone except the code that sets the header.
StrategyWhere the version livesStrengthWeakness
URI path/v1/…Visible, cacheable, easy to testVersion becomes part of the URL
HeaderX-Api-VersionClean, stable URLsInvisible, harder to debug
Query string?version=2Easy to tryClutters URLs, leaks into logs
Media typeAccept headerOne URL per resourceObscure, poor tooling support

For a public REST API, URI path versioning is the usual default: the easiest to discover and to support. Header versioning is the right call when the URL must stay stable — Stripe and GitHub both chose it, as the next section shows. The wrong move is mixing strategies on the same API.

Illustration of three API versioning strategies side by side: a browser address bar, an envelope with a header tag, and a calendar page
Four strategies, one question: where does the version identifier live — the path, a header, the query string, or the media type?

Date-based versioning in the wild: Stripe and GitHub

Two of the most-used APIs version by date, not by number.

Stripe versions its API by date. Each version is a date like 2024-06-20, sent in the Stripe-Version header or set as the account default in the dashboard; curl requests use the account default unless the header overrides it. Since the 2024-09-30.acacia release, Stripe ships a new version every month with no breaking changes, and twice a year a major release — for example Basil — that may contain them. The current version, as of this writing, is 2026-10-28.endive.

GitHub does the same for its REST API, with the X-GitHub-Api-Version header. The current version is 2026-03-10; requests without the header default to the previous version, 2022-11-28, supported until March 10, 2028. Each version is supported for at least 24 months after the next one is released, and a request naming a retired version gets a 410 Gone response. A date says when the behaviour was frozen, so the calendar — not an argument about "major" — decides.

Semantic versioning vs date-based versioning

Semantic Versioning 2.0.0 — MAJOR.MINOR.PATCH — is the numbering scheme most developers already know: increment MAJOR for incompatible API changes, MINOR for backward-compatible additions, and PATCH for backward-compatible bug fixes. Version 1.0.0 defines the public API, 0.y.z is for initial development, and a released version's contents must not be modified — any change ships as a new version.

That rule is exactly right for packages and libraries, where a client chooses a version at install time. For a live API it maps awkwardly: the MINOR and PATCH numbers describe releases the client never sees. What the client needs is one label for the frozen contract — a major number (/v1, /v2) or a date (2024-06-20). If you use SemVer for your API, put only the major number in the path, never the full triple, and do not mix the two schemes on one API.

Verified demo: one endpoint, versioned three ways

To check the three schemes really are interchangeable, I ran a tiny versioned API locally (Python, standard library only) serving one resource, /invoices, in two shapes: v1 returns total, v2 renames it to amount and adds status — the breaking change from the first section. The same endpoint answers three ways:

# 1 — URI path versioning
curl http://127.0.0.1:8765/v1/invoices
{"id": "inv_101", "total": 2500, "currency": "usd"}

curl http://127.0.0.1:8765/v2/invoices
{"id": "inv_101", "amount": 2500, "currency": "usd", "status": "paid"}

# 2 — Header versioning (same URL, version in a header)
curl -H "X-Api-Version: 2" http://127.0.0.1:8765/invoices
{"id": "inv_101", "amount": 2500, "currency": "usd", "status": "paid"}

# 3 — Date-based versioning (Stripe-style header)
curl -H "Stripe-Version: 2024-06-20" http://127.0.0.1:8765/invoices
{"id": "inv_101", "total": 2500, "currency": "usd"}

curl -H "Stripe-Version: 2025-01-01" http://127.0.0.1:8765/invoices
{"id": "inv_101", "amount": 2500, "currency": "usd", "status": "paid"}

# No version header: defaults to the oldest supported version,
# and warns that it is going away (GitHub behaves the same way)
curl -i http://127.0.0.1:8765/invoices
Deprecation: true
Sunset: Sat, 01 Aug 2027 00:00:00 GMT
{"id": "inv_101", "total": 2500, "currency": "usd"}

All six responses were produced by the local server and verified in this run — the three schemes route the same request to the same two behaviours; only where the client states the edition differs. The routing is a few lines: match the path, then the X-Api-Version header, then the Stripe-Version date, falling back to the oldest supported version with a warning when the client names none.

Deprecation, Sunset, and retiring a version without breaking anyone

Deprecation is not removal — it is a promise with a date on it. The sequence is always the same: announce the deprecation, warn clients on every response, give them a real window to migrate, then remove the version. GitHub shows the machinery: while a version approaches shutdown, responses carry a Deprecation header with the date it starts closing down and a Sunset header (RFC 8594) with the date it is removed — after which requests return 410 Gone. The 24-month window is the part clients plan around: nobody can migrate on a week's notice.

Kubernetes applies the same discipline on a longer clock: its policy forbids removing a generally available API version within a major version, deprecates beta versions no more than 9 months or 3 minor releases after introduction, and stops serving them 9 months or 3 minor releases after deprecation. A deprecated endpoint also returns a Warning header on every request, so the client sees the notice in its own logs instead of in a changelog it never reads.

Default to URI path versioning unless you have a reason not to — the most visible and the easiest to support. Choose header versioning when the URL must stay stable across upgrades, and date-based versions when you release continuously and want the calendar to settle what counts as a new edition. Write it down before your first breaking change, not after: versioning designed under pressure is how APIs end up with /v1, /v2, and a ?version=3 on the same endpoint. Our API gateway guide shows where version routing usually lives, and our rate limiting guide covers the other headers — 429 and Retry-After — your clients will meet.

Illustration of an API sunset: a sun setting on the left and a signpost with two arrows and a calendar page on the right
Sunset is a date, not a surprise: announce it, warn on every response, then remove the version.

API versioning is the discipline of changing a contract without breaking the clients that depend on it: label each edition, keep old editions working, make additive changes in place, and retire old versions on a published date. URI path versioning is the simplest default; header and date-based versioning are what Stripe and GitHub use at scale. For the authoritative texts, read the Stripe API versioning docs and the GitHub API versions docs. Our API pagination guide covers the next contract decision: how big lists are split into pages.

Frequently asked questions

What is API versioning in simple terms?
API versioning is publishing an API in labelled, parallel editions — v1, v2, or a date like 2024-06-20 — so you can change how the API works without breaking the apps already using it. Each version is a frozen promise: old clients keep the behaviour they built against, and new clients opt into the new behaviour when they are ready.
What is the difference between URI versioning and header versioning?
URI versioning puts the version in the address, like /v1/invoices and /v2/invoices — visible, easy to test in a browser, and easy to cache. Header versioning keeps one address and sends the version in a request header, like X-Api-Version: 2 — cleaner URLs, but invisible in the address bar and harder to share or debug. URI versioning is the most common choice for public REST APIs.
What is a breaking change in an API?
Any change that can make a correctly written client fail or behave wrongly: removing an endpoint, a parameter, or a response field; renaming a field; adding a required parameter; making an optional parameter required; changing a field's type; removing enum values; or changing authentication requirements. Adding things — a new endpoint, an optional parameter, a new response field — is not breaking, because old clients can safely ignore what they do not know.
Should I use semantic versioning for my API?
Semantic Versioning (MAJOR.MINOR.PATCH) is designed for packages and libraries, not live APIs — but its rule still applies: bump the major number only when you break the contract. For a live API, put only the major number in the path (/v1, /v2) and never the full triple: clients should not have to track your patch releases. Stripe and GitHub skip SemVer entirely and use dates instead, because a date names the day the behaviour was frozen.
How does Stripe version its API?
Stripe versions its API by date. Each version is a date like 2024-06-20, sent in the Stripe-Version header (or set as the account default in the dashboard). Since the 2024-09-30.acacia release, Stripe ships monthly versions with no breaking changes, and twice a year a major release — for example Basil — that may contain breaking changes. Upgrading to a monthly release should not require code changes; upgrading to a major release can.
How does GitHub version its API?
GitHub versions its REST API by date, sent in the X-GitHub-Api-Version header — the current version is 2026-03-10. Requests without the header default to the previous version, 2022-11-28, which stays supported until March 10, 2028. Each version is supported for at least 24 months after the next one is released, and a request naming a retired version gets a 410 Gone response.
What is the Sunset header?
The Sunset header (RFC 8594) tells a client the exact date an API version will be removed, so the client can plan its migration instead of discovering the removal from a failed request. GitHub pairs it with a Deprecation header that names the date the version starts closing down. After the sunset date, requests to that version return 410 Gone.
When should I create a new API version?
Only when a change breaks the documented contract and compatibility cannot reasonably be preserved — a field removed or renamed, a type changed, a parameter made required. If the change is additive (a new field, a new optional parameter, a new endpoint), ship it in the existing version: every client that does not know about it keeps working. A new version is a promise to run two APIs side by side, so each one should earn its keep.

Related articles

Try the free tool