What is API versioning in one sentence?

API versioning is how you evolve an API over time — including breaking changes — without disrupting existing clients that still depend on the old behavior.

What is a breaking change in an API?

A change that would break existing clients: removing a field or endpoint, renaming a field, making an optional parameter required, or changing a response type or error format. Adding optional fields is usually non-breaking.

What are common versioning strategies?

URL path versioning (/v1/users), header or media-type versioning (Accept: application/vnd.api.v2+json), and query-parameter versioning. URL path versioning is the most common because it is the most visible and easiest to route and cache.

How does versioning work in GraphQL?

GraphQL typically avoids version numbers. Instead you add new fields and deprecate old ones with the @deprecated directive, evolving a single schema continuously rather than shipping a v2.

What is a good deprecation policy?

Announce deprecations clearly, return Deprecation and Sunset headers, give clients a generous migration window with documentation, and monitor traffic on the old version before you remove it.

Glossary · APIs

What is API Versioning?

API versioning is how you change an API over time — including in ways that would otherwise break things — without pulling the rug out from under the clients already using it. Once another team or customer integrates with your API, their code depends on its exact shape, and versioning is the contract that lets you keep improving while their integration keeps working.

Why it exists

An internal function can be refactored at will — the compiler finds every caller. A published API cannot, because the callers are other people's systems you do not control and cannot recompile. The moment you ship a REST API that someone integrates with, its response shapes and behaviors become a promise. Versioning is how you keep that promise to existing clients while still moving the API forward for new ones.

Breaking vs non-breaking

The whole discipline turns on one distinction. Non-breaking changes — adding a new optional field, a new endpoint, a new optional parameter — are safe; old clients simply ignore what they do not know about. Breaking changes — removing or renaming a field, making an optional parameter required, changing a type or an error format — will crash existing integrations. Non-breaking changes can ship into the current version. Breaking changes are precisely what a new version is for.

Where the version lives

There are three common places to put it. URL path versioning — /v1/users, /v2/users — is the most popular because it is visible, trivial to route, and easy to cache. Header or media-type versioning — Accept: application/vnd.api.v2+json — keeps URLs stable and is considered more "RESTful" by purists, at the cost of being harder to test and cache. Query-parameter versioning exists but is the least common. There is no universally correct choice; consistency matters more than the specific scheme.

The GraphQL approach

GraphQL deliberately sidesteps version numbers. Because clients request only the fields they want, you can add new fields freely without affecting anyone, and retire old ones gradually using the @deprecated directive while you watch usage decline. The result is one continuously evolving schema rather than a wall ofv1/v2 endpoints — a genuinely different philosophy of change management, with its own tradeoffs around tooling and discipline.

Deprecation is the hard part

Adding a new version is easy; retiring an old one without angry customers is where teams struggle. A humane deprecation policy announces changes early, returns Deprecation and Sunset headers so clients can detect they are on the way out, ships migration guides, and — crucially — monitors live traffic on the old version before removing it. An OpenAPI spec helps here, because it makes the differences between versions explicit and machine-readable rather than buried in changelog prose.

At QUANT LAB

We bake versioning in from the first endpoint, because retrofitting it after launch is painful. Our API development work establishes a clear policy up front — what counts as breaking, how versions are addressed, how long old ones are supported — and backs it with an OpenAPI spec, deprecation headers, and traffic monitoring so a sunset is a managed event, not a surprise outage for someone's integration. The goal is an API you can evolve for years without breaking the people who trusted it.

Long-form deep-dives that use this term

All posts

Related terms

Evolving an API without breaking clients?

We design versioning and deprecation policies that let your API grow for years without breaking integrations. Book a 30-minute call.

API development