What Is API Versioning and How It Works

One bad API update can break thousands of applications overnight. That’s not hypothetical. It happens when teams push breaking changes without a versioning strategy in place.

So what is API versioning, and why does it matter for every team building or consuming APIs? At its core, it’s the practice of managing changes to an API so that existing integrations keep working while new features ship safely.

This guide covers how API version control works in practice, from URI path and header-based strategies to how REST, GraphQL, and gRPC each handle change differently. You’ll also learn about backward compatibility, deprecation timelines, and the most common mistakes that lead to zombie endpoints and broken client trust.

What is API Versioning

API versioning is the practice of assigning unique identifiers to different iterations of an API so that changes, updates, and deprecations can happen without breaking existing client integrations.

Think of it this way. You have an API that hundreds or thousands of applications depend on. You need to rename a field, change a response structure, or remove an endpoint. Without versioning, every one of those applications breaks the moment you push that change to production.

Versioning gives you a controlled path forward. Consumers keep using the version they built against. You ship improvements on a new version. Both coexist until you’re ready to retire the old one.

Treblle’s 2024 Anatomy of an API report found that 71% of APIs use some form of versioning. That still leaves roughly 30% without it, which, considering APIs nearly doubled in complexity from 22 to 42 endpoints on average in a single year, is a tricky position to be in.

A quick clarification that trips people up: API versioning and semantic versioning are related but different things. Semantic versioning (SemVer) is a numbering convention (MAJOR.MINOR.PATCH) used for software libraries and packages. API versioning borrows from that concept but applies it specifically to the contract between an API provider and its consumers.

The contract part matters. An API version is a promise. It says “if you send this request, you’ll get this response.” Breaking that promise without warning is how you lose developer trust fast.

Versioning also sits at the center of the broader app lifecycle. APIs don’t exist in isolation. They’re part of a living software system where frontend clients, mobile apps, third-party integrations, and internal microservices all depend on stable endpoints.

Why APIs Need Versioning

APIs change. That’s not a possibility. It’s a certainty.

Security patches, new features, performance fixes, regulatory requirements. All of these force modifications to an API’s behavior, request parameters, or response structures over time.

The problem is that some of these modifications are breaking changes. Renaming a property, changing a data type, removing an endpoint, turning an optional parameter into a required one. Any of these can cause dependent applications to fail without warning.

According to the 2024 Postman State of the API Report, 68% of enterprises cite versioning as a top challenge in API lifecycle management. And Cloudflare’s 2024 API Security report shows that 57% of all internet traffic is now API requests. The scale of potential breakage is massive.

What Happens Without Versioning

Production failures. That’s the short answer.

When an API provider pushes a breaking change without a version boundary, every consumer application that relied on the old behavior stops working correctly. Data corruption, unexpected errors, and cascading failures across dependent services.

The 2024 lunar.dev API consumer survey of 200 companies found that 36% already spend more time troubleshooting APIs than building new features. Without versioning, that number gets worse. 88% of companies reported dealing with API issues on a weekly basis.

The API Contract

Every API operates on an implicit contract with its consumers. You expose endpoints. Developers build against them. They expect consistent behavior.

Versioning formalizes that contract. It says: “Version 1 behaves this way. Version 2 introduces these changes. You choose when to migrate.”

This matters more for external-facing APIs than internal ones. If your only consumer is your own frontend, you can coordinate deployments. But when Stripe, GitHub, or Twilio push a change, they have millions of integrations to protect. Stripe processes over 500 million API requests daily. A careless breaking change at that scale would be catastrophic.

Real-World Triggers for New Versions

Security vulnerabilities: A flaw in authentication logic or data exposure requires an immediate fix that changes request/response behavior.

Renamed properties: Renaming username to username seems minor. It breaks every client parsing the old field name.

Structural changes: Switching a response property from a flat array to a nested object with pagination metadata.

Removed endpoints: Consolidating two endpoints into one, or dropping legacy functionality entirely.

The broader software development process accounts for this kind of change through release planning and backward compatibility checks. API versioning is the mechanism that makes those plans executable without breaking things in production.

How API Versioning Works

API versioning works through a lifecycle: introduce a new version, maintain the old version alongside it, deprecate the old version, and eventually sunset it.

The whole point is coexistence. Multiple API versions run simultaneously on the same server infrastructure, each responding according to its own contract. A client pinned to v1 gets v1 behavior. A client on v2 gets the updated response structure, new fields, or changed authentication.

Version negotiation (figuring out which version a client wants) happens through one of several mechanisms, depending on your strategy. It could be part of the URL path, a request header, or a query parameter. We’ll get into each approach below.

The Version Lifecycle

Introduction: A new version ships alongside the current one. Consumers are notified through changelogs, migration guides, and (if you’re doing it right) advance notice periods.

Coexistence: Both versions run in parallel. New consumers default to the latest version. Existing consumers stay on their current version until they’re ready to upgrade.

Deprecation: The old version gets marked as deprecated. It still works, but consumers receive warnings (often through response headers) that support will end on a specific date.

Sunsetting: The old version gets turned off. Requests to it return errors. Done.

Adobe Workfront, for example, releases new API versions roughly twice per year and supports each for three years after release. GitHub commits to at least 24 months of support for each REST API version. These aren’t arbitrary timelines. They give consumers realistic windows to plan and execute migrations.

Breaking vs. Non-Breaking Changes

Not every change needs a new version. The distinction between breaking and non-breaking changes determines when you bump the version number.

Additive changes (new optional fields, new endpoints) are safe. They don’t alter existing behavior, so well-built clients just ignore what they don’t recognize.

Anything that removes, renames, or restructures existing behavior is a breaking change. That’s when you need a new version.

This distinction connects directly to how teams handle change management in their projects. Knowing what constitutes a breaking change lets you plan releases without surprises.

URI Path Versioning

The most common approach. You put the version number directly in the URL.

GET /v1/users GET /v2/users

Stripe uses /v1/ in its URL path. Google APIs follow the same convention. Facebook’s Graph API goes with /v10.0/, /v11.0/, and so on.

It’s popular for good reasons. The version is visible, easy to understand, and simple to route at the server or API gateway level. You can test it in a browser. You can share a versioned URL with a colleague and they immediately know which version they’re looking at.

The trade-off? REST purists argue that a URI should identify a resource, not a version of a resource. /v1/users and /v2/users are technically different URIs pointing to the same conceptual resource. In practice, most teams don’t care about that distinction. It works, it’s clear, and it’s what developers expect.

Header-Based Versioning

Instead of baking the version into the URL, you pass it as an HTTP header.

GitHub’s REST API uses this approach. You include X-GitHub-Api-Version: 2022-11-28 in your request header. The URL stays clean. The version travels with the request metadata.

Stripe does something hybrid. The URL path stays at /v1/, but the real versioning happens via the Stripe-Version header, using date-based values like 2024-09-30.acacia.

Pros: Cleaner URLs, better REST compliance, separates the resource from its version.

Cons: Harder to test casually (you can’t just type a URL in a browser), less visible to developers who are browsing documentation, and clients need to understand which headers to set.

Query Parameter Versioning

Pass the version as a query string parameter.

GET /users?version=2

Easy to implement. Easy to default to the latest version when the parameter is missing. Some Google services have used this pattern.

But it has real downsides. Caching gets complicated because the version becomes part of the query string, which many caching layers treat differently. And making the version parameter optional creates a risk: if a client forgets to include it, they might get a different version than expected.

It’s the least common of the three approaches in production REST APIs.

API Versioning Strategies Compared

There’s no single correct answer. Each strategy comes with trade-offs, and what works for a public API serving millions of developers looks different from what works for an internal microservice.

URI path versioning wins the popularity contest. Most public APIs use it because it’s obvious and requires zero explanation. Developers see /v2/ in the URL and immediately understand what’s happening.

Header-based versioning is gaining ground, especially with large platforms. GitHub switched to it. Stripe combines it with URI paths. The Gartner 2024 API Strategy Survey found that REST still dominates API usage at 85%, and within that ecosystem, the trend is toward more flexible versioning mechanisms that don’t clutter endpoint URLs.

Date-Based Versioning

Stripe popularized this. Instead of incrementing v1, v2, v3, they use dates: 2024-09-30, 2024-12-18, etc.

When you create a Stripe account, your integration gets pinned to the current version. Even if Stripe ships dozens of updates over the next few years, your code keeps working exactly as it did on the day you integrated. You upgrade when you’re ready, not when Stripe forces you.

This solves the biggest problem with major-version bumps: forced migrations. Going from v1 to v2 often means rewriting large chunks of integration code. Date-based rolling versions make each upgrade smaller and more manageable.

SailPoint adopted a similar approach with annual version releases (v2024, v2025) for their Identity Security Cloud APIs, supporting each version for at least three years.

When URI Path Still Makes Sense

If your API is public-facing, your developer audience is broad, and you want zero ambiguity, URI path versioning is still the safest default.

It plays well with load balancers, reverse proxies, and API gateways that route based on URL patterns. No custom header parsing needed. No content negotiation complexity.

For internal APIs within a microservices architecture, header-based versioning or even no versioning (just careful additive changes) might be the better fit. The overhead of maintaining versioned URL paths across dozens of internal services adds up fast.

API Versioning and Backward Compatibility

Versioning and backward compatibility are two sides of the same problem. Versioning is the mechanism. Backward compatibility is the goal.

Every time you ship a new API version, you’re making a decision about how long and how well you’ll support the old one. That decision has real engineering costs.

What Backward-Compatible Changes Look Like

Adding a new optional field to a response body. Existing clients ignore it. New clients use it.

Adding a new endpoint that doesn’t affect existing routes. No conflict, no breakage.

Adding optional query parameters that default to previous behavior when omitted.

These are all safe. You don’t need a new version for any of them. Well-designed clients should be resilient to additive changes. If your client breaks because the API returned an extra field, that’s a client-side bug, not an API problem.

The Cost of Maintaining Multiple Versions

Here’s the part that nobody enjoys talking about. Every active version is a maintenance burden.

Each version needs its own test coverage. Each version needs documentation. Each version needs monitoring. Bug fixes sometimes need to be backported across versions. And your codebase accumulates conditional logic to handle different version behaviors.

Moldstud research indicates that 60% of companies implementing clear versioning mechanisms can reduce breaking changes by 50%. But that reduction comes with the overhead of actually maintaining those mechanisms.

Stripe’s approach to this is instructive. They built an internal framework where each version change is encapsulated in a small, self-contained module. The system generates the latest response, then applies “downgrade” transformations in reverse chronological order until it matches the version the client is pinned to. The complexity is real, but it’s isolated and manageable.

When to Drop a Version

You can’t support old versions forever. At some point, the maintenance cost outweighs the benefit.

Standard practice is to announce a deprecation timeline, communicate it clearly through technical documentation, changelogs, and direct outreach, then enforce it.

GitHub supports each REST API version for at least 24 months. Box supports each version for at least 12 months. Adobe Workfront gives three years. Pick a timeline that matches your consumer base. Enterprise APIs with slow-moving clients need longer windows. Fast-moving startup APIs can get away with shorter ones.

API Versioning in REST vs. GraphQL vs. gRPC

The versioning approach depends heavily on your API architecture. REST, GraphQL, and gRPC each handle change differently by design.

REST API Versioning

REST is where versioning is most established and most necessary. Because REST endpoints return fixed response structures, any change to that structure can break consumers.

All three strategies (URI path, header, query parameter) apply to REST. The Gartner 2024 survey confirms REST still holds 85% of API usage, with alternatives like GraphQL at 19% and gRPC at 11%.

The RESTful API model is straightforward: you define resources, expose them through endpoints, and version those endpoints when breaking changes are needed. Most developers encounter API versioning in a REST context first.

GraphQL’s “No Versioning” Philosophy

GraphQL takes a fundamentally different position. The official GraphQL documentation states that the schema should evolve continuously rather than through discrete version bumps.

Why? Because GraphQL clients explicitly request only the fields they need. If you add a new field, existing clients never see it (they didn’t ask for it). If you need to replace a field, you add the new one, mark the old one with @deprecated, and give consumers time to migrate.

This makes additive changes painless. No version bump required. The GraphQL API spec includes first-class deprecation support and introspection tools that let developers see exactly which fields are deprecated and why.

But saying “GraphQL doesn’t need versioning” is an oversimplification. You still have to handle breaking changes eventually. Removing a type, renaming a field, changing the semantics of an existing query. Those are real problems, and the @deprecated directive doesn’t define when a deprecated field actually gets removed.

Apollo’s 2024 survey found that teams using GraphQL saw up to a 60% reduction in over-fetching compared to REST, partly because the query model naturally supports evolution without full version bumps.

gRPC and Protocol Buffers

gRPC uses Protocol Buffers (protobuf) for message serialization, and protobuf has backward compatibility built into its design.

Each field in a protobuf message gets a unique number. You never reuse or reassign those numbers. Old clients ignore new fields. New clients handle missing old fields gracefully through default values. This gives you a form of automatic backward compatibility without explicit version management.

It’s not bulletproof. If you need to change a field’s type, rename a service method, or restructure your message hierarchy, you still need a versioning strategy. But for typical evolution (adding fields, adding new RPC methods), protobuf handles it cleanly.

gRPC’s approach works well within internal back-end development environments where both client and server are controlled by the same team. For public-facing APIs, REST with explicit versioning or GraphQL with schema evolution are more common choices.

The choice between these isn’t just about versioning. It’s about your entire tech stack, your consumer base, and your team’s ability to manage the overhead of whichever approach you pick.

Common API Versioning Mistakes

Most versioning problems aren’t technical. They’re organizational. Teams skip planning, over-engineer the wrong things, and forget to retire what they’ve replaced.

Treblle’s 2024 report found that 35% of all API endpoints are zombie endpoints, up from 24% in 2023. That’s old, unmanaged versions still running in production with nobody watching them. Radware’s 2025 data shows attacks on APIs grew by 41% in 2024, and zombie endpoints were a primary target.

Versioning Too Aggressively

Bumping the version for every minor change is a common trap. A new optional field doesn’t need a v3. An added endpoint doesn’t need a v3 either.

Every new version multiplies your testing and documentation burden. Only create a new version for actual breaking changes. If you can make the update backward-compatible, do that instead.

Salesforce releases a new API edition three times a year and supports 20+ past versions simultaneously. That’s the cost of aggressive versioning at scale. Most teams can’t sustain that.

No Deprecation Timeline

Shipping a new version without a plan to retire the old one is how you end up maintaining five active versions with no end in sight.

What a deprecation plan looks like:

• Announce the deprecation date at launch of the new version
• Set a sunset date (12 to 24 months is typical for external APIs)
• Communicate through changelogs, headers, and direct outreach

One DEV Community post describes keeping /v1 alive “just for a few months” that turned into two years of unmaintained traffic. Sunsetting is a project, not a toggle.

Inconsistent Versioning Across Endpoints

Some teams version their /users endpoint at v2 while /orders stays at v1. Clients end up hitting a mix of v1, v2, and v3 endpoints in the same request flow.

Each version might use a different error format, different authentication approach, or different response structure. That creates confusion and increases API integration complexity for every consumer.

Pick one versioning approach and apply it consistently. If you go with URI path versioning, every endpoint uses it. If you go with headers, every endpoint uses headers.

Ignoring Internal APIs

Teams tend to version public APIs carefully and skip versioning for internal services entirely. Then a refactor breaks three internal microservices that nobody expected to be affected.

Axway’s 2024 survey found that 74% of organizations reported more than 20% of their APIs as unmanaged. Internal APIs are the biggest source of that blind spot.

Internal APIs deserve at least basic version tracking, even if it’s just a header convention. The cost of code refactoring when unversioned internal APIs break is always higher than the cost of planning ahead.

How to Choose an API Versioning Approach

The right choice depends on three things: who consumes your API, how often you expect breaking changes, and what your infrastructure supports.

There’s no universal best practice here. But there is a default that works for most teams, and clear reasons to deviate from it.

Public vs. Internal APIs

Public APIs need the most visibility. External developers should never have to guess which version they’re using. URI path versioning is the safest default here.

Internal APIs within a containerized microservice setup can often avoid explicit versioning by sticking to additive-only changes and coordinating deployments.

What Your Infrastructure Supports

Your API gateway, framework, and deployment pipeline influence which strategy is practical.

Kong, Apigee, and AWS API Gateway all handle URI-based routing natively. Header-based versioning requires custom configuration in most gateways.

Frameworks like FastAPI (Python) and ASP.NET have built-in versioning support. Express.js (Node) leaves it to you. Your tech stack for web development shapes what’s easy to implement and what turns into a maintenance headache.

The Default Recommendation

If you’re building a new API and aren’t sure which way to go: use URI path versioning.

It’s the most widely understood, the easiest to implement, and it works with almost every gateway, proxy, and monitoring tool out of the box. The Gartner 2024 API Strategy Survey confirms that the majority of organizations still build REST APIs with path-based versioning as the primary mechanism.

Deviate from this default when you have a strong reason. If you’re building a platform with long-lived integrations (like Stripe), date-based header versioning is worth the investment. If you’re running a GraphQL schema, lean into continuous evolution instead.

API Deprecation and Version Sunsetting

Versioning doesn’t end when you ship a new version. The other half of the lifecycle is retiring the old ones.

Deprecation signals intent. Sunsetting is the actual removal. Getting this wrong (too fast, too quiet, or not at all) damages developer trust and creates security holes.

What Deprecation Signals to Consumers

A deprecated API version still works. That’s the key distinction.

Deprecation is a warning, not a shutdown. It tells consumers: “This version is no longer being improved. Start planning your migration. It will stop working on [date].”

The IETF formalized this with RFC 9745 (published March 2025), which defines the Deprecation HTTP response header. Combined with the Sunset HTTP header field from RFC 8594, API providers now have a standardized way to signal both when a resource was deprecated and when it will become unresponsive.

Sunset Headers and Communication

Technical signals:

• Deprecation: @1688169599 (timestamp marking when deprecation started)
• Sunset: Sun, 30 Jun 2024 23:59:59 UTC (when the endpoint goes dark)
• Link header pointing to migration documentation

Non-technical signals:

• Changelog entries
• Email notifications to registered developers
• Blog posts and developer portal announcements

GitHub pairs both approaches well. When they released REST API version 2026-03-10, they committed to supporting the previous version (2022-11-28) for at least 24 months, with announcements through their changelog, docs, and email to active developers.

Real-World Deprecation Timelines

How long should you support an old version? It depends on your consumer base.

Stripe’s model is the most consumer-friendly. Your account stays pinned to whatever version you started with. But they absorb massive internal engineering cost to make that work, maintaining over a decade of backward compatibility through layered transformation modules.

The Zombie Endpoint Problem

When deprecation happens on paper but not in practice, you get zombie endpoints. Old versions that nobody officially supports but that are still live, still receiving traffic, and still vulnerable.

The Salt Security 2024 State of API Security Report found that 37% of organizations experienced an API security incident in the past year (up from 17% in 2023). Zombie APIs were identified as the number one security concern across four consecutive surveys.

Proper software configuration management and continuous deployment practices help here. When you deprecate a version, put a hard sunset date in the pipeline. Don’t leave it running as a “just in case.” That’s how zombie endpoints are born.

Your build pipeline should include checks for deprecated endpoints. If a version has passed its sunset date, remove the routes. Remove the documentation. Remove the monitoring. Clean retirement is the only kind that works.

FAQ on What Is API Versioning

What is API versioning in simple terms?

API versioning is the practice of assigning unique identifiers to different iterations of an API. It lets providers ship updates, fix bugs, and add features without breaking existing client integrations that depend on older behavior.

Why is API versioning necessary?

APIs change over time. Without versioning, any breaking change (renamed fields, removed endpoints, altered response structures) instantly breaks every application consuming that API. Versioning protects consumers during transitions.

What are the main types of API versioning?

The three most common approaches are URI path versioning (/v1/users), header-based versioning (custom HTTP headers like X-API-Version), and query parameter versioning (?version=2). URI path is the most widely adopted for REST APIs.

What is the difference between API versioning and semantic versioning?

Semantic versioning (SemVer) is a numbering convention for software packages using MAJOR.MINOR.PATCH format. API versioning applies similar concepts specifically to the contract between an API provider and its consumers.

How does Stripe handle API versioning?

Stripe uses date-based rolling versions. Each account gets pinned to the API version active at signup. Updates are opt-in. Developers upgrade when ready by changing the Stripe-Version header, not when Stripe forces them.

Does GraphQL need API versioning?

GraphQL encourages schema evolution over traditional versioning. Clients request only the fields they need, so additive changes don’t break anything. The @deprecated directive handles field retirement. But breaking changes still require a migration strategy.

What is a breaking change in an API?

A breaking change is any modification that forces consumers to update their code. Renaming a property, removing an endpoint, changing a data type, or making an optional parameter required all qualify as breaking changes.

How long should you support an old API version?

It depends on your consumer base. GitHub supports each version for at least 24 months. Adobe Workfront gives three years. Stripe maintains backward compatibility indefinitely. Enterprise APIs generally need longer deprecation windows than internal ones.

What is the Sunset HTTP header?

Defined in IETF RFC 8594, the Sunset header tells API consumers when an endpoint will become unresponsive. Combined with the Deprecation header (RFC 9745), it gives clients a standardized, machine-readable signal to plan their migration.

What are zombie API endpoints?

Zombie endpoints are old API versions that remain active in production after being replaced. They typically lack security updates and monitoring. Treblle’s 2024 data shows 35% of all endpoints fall into this category, up from 24% in 2023.

Conclusion

Understanding what is API versioning comes down to one thing: managing change without breaking trust. Every API evolves. The question is whether you handle that evolution through planning or through production incidents.

The strategy you pick (URI path, header-based, date-based, or schema evolution in GraphQL) matters less than applying it consistently. Pair it with clear deprecation timelines, proper sunset headers, and documented migration guides.

Don’t skip internal APIs. Don’t let old versions linger as zombie endpoints. And don’t create a new version for every minor tweak.

Whether you’re building a public REST API or managing gRPC services across a distributed back-end infrastructure, version management is part of the job. Treat your API lifecycle with the same rigor you give your deployment pipeline, your test coverage, and your release process. Your consumers are counting on it.

• Author
• Recent Posts

Bogdan Sandu

Bogdan Sandu specializes in web design, focusing on creating user-friendly websites, and innovative UI kits.

Many of his resources are available on various design marketplaces and for free on Codepen.

Over the years, he's worked with a range of clients and contributed to design publications like Design Your Way, Designmodo, WebDesignerDepot, WPDean, Speckyboy, and Slider Revolution among others.

Latest posts by Bogdan Sandu (see all)

• From AI Draft to Final Document: Writing, Exporting, and Annotating PDFs Without Desktop Software - May 21, 2026
• The Best Android Launchers for App Organization - May 20, 2026
• What Are the Best PEO Services for Web Development Businesses? - May 20, 2026