API Versioning Strategies: URL Path, Headers, Semantic Versioning, and Deprecation [2026]

Every API that has external consumers will eventually need to change in ways that break those consumers. The choice is not whether you will introduce breaking changes — it is whether you will do it with a versioning strategy that gives your consumers time to adapt, or without one and break their integrations without warning.

This guide covers the four primary API versioning strategies with their tradeoffs, semantic versioning applied to APIs, the deprecation lifecycle that protects both producers and consumers, and backward compatibility patterns that let you evolve APIs without breaking existing clients. By the end, you will have a framework for managing API evolution across the full lifecycle of a production API.

Breaking vs. Non-Breaking Changes

The first decision in API versioning is knowing when versioning is required. Not all API changes break clients.

Breaking changes force clients to update their code before they can continue working:

• Removing an endpoint
• Renaming a required field in a response
• Changing a field's type (string to integer)
• Adding a required field to a request body
• Changing HTTP status codes for existing conditions
• Changing authentication mechanisms

Non-breaking changes can be deployed without client updates:

• Adding new optional endpoints
• Adding new optional fields to request bodies
• Adding new fields to response bodies (clients ignore unknown fields)
• Improving response times
• Internal implementation changes with no observable behavior change

Non-breaking changes should be deployed freely without version increments — requiring a version bump for every additive change forces consumers to update unnecessarily. Breaking changes require a version strategy.

API Versioning Strategies

URL Path Versioning

URL path versioning embeds the version number directly in the resource URL: /api/v1/users, /api/v2/users. It is the most widely adopted strategy because the version is immediately visible in logs, error reports, client code, and documentation.

GET /api/v1/users/123
Accept: application/json

GET /api/v2/users/123
Accept: application/json

Advantages: complete clarity (the version is impossible to miss), easy to test (use curl, browser, or any HTTP client without special headers), straightforward CDN caching (v1 and v2 resources have different cache keys), and simple routing (a load balancer can route v1 to old containers and v2 to new containers during migration).

Disadvantages: URL proliferation as you maintain multiple versions; the purist REST objection that the resource hasn't changed, only its representation; clients may hardcode the version and never upgrade even when deprecated.

URL path versioning is the correct default for public APIs. Its operational clarity outweighs the theoretical purity concerns. When in doubt, use URL path versioning.

Custom Header Versioning

Custom header versioning passes the version in a request header rather than the URL:

GET /api/users/123
Accept: application/json
Accept-API-Version: 2

The URL remains clean across versions. The same endpoint can serve multiple versions of the API. For internal APIs consumed by teams with full control over request construction, this can be appropriate.

Disadvantages: the version is invisible in logs and browser address bars; developers forget to include the version header; testing requires a specialized client (curl with explicit headers, not a browser URL); CDN caching requires Vary headers to prevent version bleeding across cached responses.

Header versioning is most suitable for internal APIs where all consumers are internal teams with controlled HTTP clients, and URL cleanliness is a genuine requirement.

Content Negotiation

Content negotiation uses the HTTP Accept header with a vendor-specific MIME type:

GET /api/users/123
Accept: application/vnd.company.v2+json

This is the most REST-compliant approach, aligning with HTTP's native content type negotiation mechanism. It separates the version concern from both the URL and custom headers.

Disadvantages: complex to implement correctly (the server must parse Accept headers and match vendor types); difficult to test without tooling; many client libraries do not handle vendor MIME types gracefully; documentation and developer onboarding are harder because the versioning mechanism is opaque.

Content negotiation versioning suits organizations with a strong REST purity requirement and the engineering investment to build proper content negotiation infrastructure. It is rarely the right choice for external-facing APIs.

Query Parameter Versioning

Query parameter versioning appends the version as a query string: /api/users/123?version=2. It is the simplest to implement and explicit like URL path versioning. The disadvantage is that query parameters are semantically used for filtering and search — mixing versioning into query parameters creates confusion and complicates caching.

Query parameter versioning is most appropriate for legacy systems where URL structure cannot be changed without breaking other integrations.

Semantic Versioning for APIs

Semantic versioning (SemVer) defines version numbers as MAJOR.MINOR.PATCH:

• PATCH (1.0.x): bug fixes and internal improvements with no observable behavior change
• MINOR (1.x.0): new backward-compatible features (new optional endpoints, new optional fields)
• MAJOR (x.0.0): breaking changes

Applied to APIs: increment PATCH for bug fixes that don't change behavior; increment MINOR for additive changes (new endpoints, new optional request/response fields); increment MAJOR when making breaking changes that require client updates.

The practical convention for URL path versioning: expose only the MAJOR version in the URL (/v1/, /v2/). MINOR and PATCH changes are deployed without URL changes — they are transparently backward compatible. This prevents URL proliferation while still providing a clear signal of the breaking change boundary.

Pre-release versions follow SemVer conventions: v2.0.0-alpha.1, v2.0.0-beta.3, v2.0.0-rc.1. These signal to consumers that the API is unstable and subject to change. Only release candidates (RC) should be used in production integrations; alpha and beta versions are for early testing and feedback.

Deprecation Lifecycle

A deprecation policy protects consumers by giving them time to migrate before old functionality is removed. The phases:

Announcement (week 0): Publish a deprecation notice through all channels — API changelog, developer portal, email to registered API key holders, in-product notification for dashboard users. Include: what is being deprecated, when it will be removed, what the migration path is, and where to get help.

Deprecated but functional (months 1-6): The deprecated version continues to work. Responses include deprecation headers:

Deprecation: true
Sunset: Sat, 01 Jul 2026 00:00:00 GMT
Link: <https://api.example.com/v2/users>; rel="successor-version"

The Sunset header (RFC 8594) defines the date after which no guarantee of availability is made. The Link header points consumers to the replacement. Monitoring should track which clients are still calling deprecated endpoints — reach out to those clients proactively.

Sunset period (months 7-9): The deprecated endpoint begins returning HTTP 410 Gone responses for new clients, but continues serving existing API keys as the grace period winds down. Some organizations skip this phase; for critical infrastructure APIs with enterprise customers, it reduces churn significantly.

Removal (month 9+): The deprecated version is decommissioned entirely. Responses return HTTP 410 Gone with a response body that explains the deprecation and links to migration documentation.

The timeline above (6+ months) is appropriate for public APIs with external consumers. Internal APIs between teams in the same organization can use shorter deprecation windows (4-8 weeks) if the consuming teams are co-located and can coordinate directly.

Backward Compatibility Patterns

A strong versioning strategy reduces how often you need to increment the MAJOR version. These patterns extend API compatibility without breaking existing clients:

Additive responses: add new fields to response bodies freely. Clients built to the JSON specification ignore unknown fields. When Stripe adds a new field to the PaymentIntent object, existing client libraries that have not updated to know about the field continue working correctly.

Optional request parameters: add new request parameters as optional with sensible defaults. Existing clients that don't send the new parameter continue to receive the default behavior.

Field aliases: when renaming a field, support both the old and new name simultaneously during the transition period. Return both in responses; accept either in requests. Deprecate the old name with a sunset date.

Graceful degradation: deprecated fields continue to work for the sunset period. The server can internally translate the old field to the new representation, allowing clients to continue using the old API surface while migration happens.

Versioned data contracts: for complex response schema changes, return the new structure alongside the old in a single response during the transition:

{
  "price": 19.99,
  "pricing": {
    "amount": 19.99,
    "currency": "USD",
    "formatted": "$19.99"
  }
}

The old price field and new pricing object coexist. Clients on the old structure see their field unchanged; clients updating to the new structure can migrate at their own pace.

API Lifecycle Stages

Understanding the full lifecycle informs versioning decisions:

Alpha: internal testing only. Breaking changes happen freely. No SLA. Not for production use.

Beta: selected external consumers invited for early testing. Breaking changes still possible. Consumers who adopt beta accept the instability risk.

Release Candidate (RC): feature-complete with final API shape. Only critical bug fixes change behavior. The API surface tested at this stage is what ships as GA.

General Availability (GA): stable, SLA-backed, fully supported. Breaking changes require a new MAJOR version with a deprecation window.

Maintenance Mode: no new features. Security patches and critical bug fixes only. Consumers should migrate to the current GA version; deprecation timeline begins.

Deprecated: active deprecation notice with sunset date. Still functional but scheduled for removal.

Sunset: removed. HTTP 410 Gone.

Communicating lifecycle stage clearly in documentation and deprecation headers allows consumers to make informed decisions about which API versions to adopt for production integrations.

Monitoring API Version Usage

A versioning strategy only works if you know which versions your clients are using. Instrument every API request with version information in your access logs, and build dashboards that show:

• Request volume by version over time (how fast is adoption of the new version growing?)
• Number of unique API keys still using deprecated versions (how many clients need to migrate?)
• Error rates by version (is the new version performing as expected?)

When rolling out a new MAJOR version, set a migration target: by the deprecation deadline, fewer than X% of requests should still be on the deprecated version. Monitor progress weekly. For large consumers that are not migrating, proactive outreach is more effective than waiting for them to respond to deprecation email.

The most common versioning failure is not technical — it is failure to communicate. Teams that publish a deprecation notice once in a changelog and then remove the version on schedule are surprised when enterprise customers call in emergency support mode. A versioning strategy that protects consumers requires active communication, monitoring, and outreach.

Multi-Version Deployment Infrastructure

Managing multiple API versions in production requires deployment infrastructure that isolates them appropriately. Two approaches:

Container-based version isolation: each API version runs as a separate container image. Version routing happens at the load balancer or API gateway layer, which directs requests based on the URL path prefix or header value to the appropriate container. This provides complete isolation — a bug in v2 does not affect v1 stability — at the cost of running parallel infrastructure.

Code-level version branching: a single codebase handles all supported versions using internal routing. Version differences are managed through adapter layers or strategy patterns that select the appropriate behavior per version. This reduces operational overhead (fewer containers, one deployment pipeline) but increases code complexity over time as the number of supported versions grows.

For most production APIs, container-based version isolation is cleaner: the operational overhead is modest at two or three active versions, and the isolation prevents version cross-contamination. For high-traffic APIs where running parallel infrastructure is expensive, code-level branching with a strict version count limit (maximum two active MAJOR versions at any time) is a reasonable compromise.

Kubernetes multi-version pattern: deploy each version as a separate Kubernetes service, with an ingress controller routing traffic by URL prefix:

# v1 service handles /api/v1/* requests
# v2 service handles /api/v2/* requests
# Traffic weights can be adjusted during migration

This pattern enables blue-green deployments within a single version and canary deployments when rolling out a new MAJOR version — route 5% of traffic to v2, monitor error rates and latency, increase the percentage as confidence grows.

Versioning for Internal vs. External APIs

Internal APIs (service-to-service communication within your organization) and external APIs (third-party developers, partners, public) have different versioning requirements.

External APIs require: formal deprecation timelines (6+ months), public documentation updates, changelog entries for every version change, proactive outreach to consumers of deprecated versions, and multiple supported versions simultaneously.

Internal APIs can use: shorter deprecation windows (4-8 weeks) coordinated directly with consuming teams, version pinning in CI/CD to ensure all consumers upgrade together, and contract testing (Pact) to detect breaking changes before deployment rather than after.

The distinction matters for planning. Versioning overhead grows linearly with the number of active versions and quadratically with the number of consumers. Design internal APIs with an aggressive deprecation policy to limit version proliferation — supporting v1 through v4 internally because teams never upgraded creates a maintenance burden that accumulates silently over years.

Choosing Your Strategy

The decision framework:

API Type	Recommended Strategy	Versioning Approach
Public external API	URL path versioning	SemVer MAJOR in path
Internal service-to-service	URL path or header	SemVer with short deprecation window
Partner/B2B API	URL path versioning	SemVer with SLA-backed deprecation
GraphQL API	Schema evolution	Deprecation directives, additive changes

For GraphQL APIs, URL path versioning is not applicable (GraphQL has a single endpoint). Instead, use schema evolution: add fields and types freely; deprecate fields with @deprecated(reason: "...") directives in the schema; remove deprecated fields only after the standard deprecation window. The GraphQL approach to versioning — extend the schema rather than version it — works well when the schema is designed with evolution in mind from the start.

Start with URL path versioning. It is operationally clear, widely understood, and easy to implement. Adopt more complex strategies only when a specific constraint makes URL path versioning genuinely unsuitable for your context.