API Versioning Strategies: URL vs Header vs Query Parameter

Your API will change. New fields, renamed endpoints, restructured responses, authentication overhauls. The question is not whether you will need versioning, but how you will implement it. The strategy you choose affects cacheability, developer experience, routing complexity, and how gracefully your consumers can migrate. Four primary approaches exist, each with real tradeoffs that show up at scale.

TL;DR

URL path versioning (/v1/users) is the most widely adopted strategy and the safest default for public APIs. Header versioning keeps URLs clean but adds testing friction. Query parameter versioning works as a quick escape hatch but lacks rigor. Content negotiation is the most RESTful but the most complex. Stripe's date-based version pinning represents a fifth approach: no URL versioning at all, with additive-only changes and per-account API version locking.

If you are building a public API and want the most battle-tested approach, use URL path versioning. If you are Stripe-scale and can invest in version compatibility infrastructure, consider date-based version pinning.

Key Takeaways

• URL path versioning dominates — GitHub, Stripe, Twilio, Google, and Microsoft all use it as their primary strategy
• Header versioning is RESTful but painful — clean URLs come at the cost of testability and discoverability
• Query parameters are an anti-pattern for permanent versioning — use them for migration periods, not long-term strategy
• Content negotiation is theoretically ideal but practically rare — tooling and developer understanding lag behind
• The best versioning strategy is needing fewer versions — invest in additive-only changes and strong deprecation policies
• Breaking vs non-breaking classification determines your versioning frequency — most changes can be additive

Strategy Comparison

Criteria	URL Path	Header	Query Param	Content Negotiation
Visibility	High — in the URL	Low — hidden in headers	Medium — in query string	Low — hidden in headers
Simplicity	Simple	Medium	Simple	Complex
RESTfulness	Moderate — URL pollution	High — clean URLs	Low — feels like a hack	Highest — media type driven
Cacheability	Excellent — distinct URLs	Requires Vary header	Tricky — parameter ordering	Requires Vary header
Routing	Native — nginx, gateways	Custom header routing	Custom parameter routing	Complex content-type routing
Testability	Easy — paste URL in browser	Requires curl/Postman	Easy — append to URL	Requires curl/Postman
Adoption	Most common	Moderate	Low	Rare
Gateway support	Universal	Partial	Partial	Limited

---

Deep Dive: URL Path Versioning

Format: /api/v1/users, /api/v2/users

The most common approach by a significant margin. The version number is embedded directly in the URL path, making it immediately visible to anyone reading the request.

GET https://api.github.com/v3/repos/octocat/hello-world
GET https://api.stripe.com/v1/customers
GET https://api.twilio.com/2010-04-01/Accounts
GET https://graph.microsoft.com/v1.0/me

Why it works:

URL path versioning aligns with how infrastructure already operates. Load balancers, API gateways, reverse proxies, and CDNs all route based on URL paths natively. No custom configuration is needed. Each version produces a distinct URL, which means HTTP caching works without any special headers. Documentation is straightforward — each version gets its own OpenAPI specification, and developers can see exactly which version they are calling.

Why it falls short:

REST purists argue that a resource's identity should not change because the API version changes. /v1/users/123 and /v2/users/123 refer to the same user, but they have different URIs. This violates the REST constraint that a resource should have a single, stable identifier. In practice, this is rarely a problem that developers encounter, but it matters for HATEOAS and hypermedia-driven APIs.

The bigger practical concern is maintenance. Each major version increment means maintaining parallel route handlers, controllers, and tests. If you have three active API versions, you are maintaining three codebases. Most teams mitigate this with internal abstraction layers — the v1 and v2 endpoints call the same underlying service, with transformation layers converting between response formats.

Best for: Public APIs, developer-facing APIs, APIs consumed by external teams. When simplicity and discoverability matter more than REST purity.

---

Deep Dive: Header Versioning

Format: Accept: application/vnd.api+json;version=2 or custom header X-API-Version: 2

Version information travels in the HTTP headers, leaving the URL clean. The same URL returns different representations depending on the version specified.

GET /repos/octocat/hello-world
Accept: application/vnd.github.v3+json

GET /repos/octocat/hello-world
Accept: application/vnd.github.v3.raw+json

GitHub supports both URL path and header versioning. Their API defaults to v3 when no Accept header is specified, but you can use the Accept header to access preview features and specific media types.

Why it works:

Header versioning is more aligned with REST principles. The URL identifies the resource, and the headers describe how the client wants to interact with it. This maps naturally to the concept of content negotiation — the same resource can have multiple representations, and the client selects which one it wants.

Individual resources can version independently. Your /users endpoint might be on version 3 while /orders is on version 5, without cluttering URLs with different version numbers on different paths.

Why it falls short:

Testing friction is the biggest issue. You cannot paste a URL into a browser and see what happens. Every request requires curl, Postman, or a similar tool with header support. This makes API exploration harder for developers who are just getting started.

Caching becomes more complex. When the same URL returns different responses based on headers, you need the Vary header to tell caches and CDNs which request headers affect the response. Misconfigured Vary headers lead to stale cache entries or cache collisions between versions.

API gateway routing on custom headers is not universally supported. While most modern gateways (Kong, AWS API Gateway, Apigee) can route based on headers, the configuration is more involved than path-based routing.

Best for: Internal APIs, APIs where REST purity is a requirement, APIs where different resources version at different rates.

---

Deep Dive: Query Parameter Versioning

Format: /api/users?version=2 or /api/users?v=2

The version is passed as a query string parameter. Google Maps API has used this approach historically.

GET https://maps.googleapis.com/maps/api/geocode/json?address=Seattle&key=API_KEY

Why it works:

Implementation is trivial — read a query parameter and route accordingly. The version is visible in the URL, so developers can see it. If the parameter is omitted, the API defaults to the latest version (or a pinned version), making it optional.

Why it falls short:

Semantically, query parameters represent filters, options, and modifiers for the resource being requested. The API version is not a filter on the resource — it is a contract defining the entire shape of the response. Mixing contract metadata with resource parameters feels like a misuse of query strings.

Caching is unreliable. Query parameter ordering, encoding, and optional presence create ambiguity. /users?version=2&sort=name and /users?sort=name&version=2 are the same request but may be treated as different cache keys by some intermediaries.

Routing layers typically do not inspect query parameters for routing decisions. This means version routing happens at the application layer rather than the infrastructure layer, which adds latency and complexity.

Best for: Quick versioning during migration periods, internal APIs with short lifespans, or as a testing mechanism alongside a primary versioning strategy.

---

Deep Dive: Content Negotiation

Format: Accept: application/vnd.company.resource.v2+json

The most RESTful approach. The version is encoded in a custom media type. Different versions are treated as different representations of the same resource, which is exactly what HTTP content negotiation was designed for.

Accept: application/vnd.github.v3+json
Accept: application/vnd.github.v3.raw+json
Accept: application/vnd.github.v3.html+json

Why it works:

This is the theoretically correct approach according to REST principles. A resource can have multiple representations (JSON, XML, different versions), and the client uses the Accept header to specify which representation it wants. Versioning is just another dimension of representation.

Individual resources version independently. You can version the user representation without touching orders. Different clients can negotiate different versions of different resources simultaneously.

Why it falls short:

Developer understanding is the biggest barrier. Most API consumers do not think in terms of media types and content negotiation. The concept requires explaining MIME types, vendor media types, and the Accept/Content-Type negotiation process. This is a significant documentation burden.

Tooling support is poor. API testing tools, code generators, and documentation platforms handle standard application/json well. Custom vendor media types like application/vnd.company.users.v2+json receive inconsistent support across the ecosystem.

Debugging is difficult because the version is not visible in logs, URLs, or most monitoring tools. Tracing a request to a specific API version requires inspecting headers at every hop.

Best for: Internal APIs with sophisticated consumers who understand HTTP semantics. Rarely appropriate for public APIs.

---

The Fifth Strategy: No URL Versioning (Stripe's Date-Based Approach)

Stripe takes a fundamentally different approach. They maintain a single URL path (/v1/) and handle versioning through date-based API versions assigned per account.

Stripe-Version: 2024-12-18

How it works:

1. Every Stripe account is pinned to the API version that existed when the account was created
2. Breaking changes create a new dated version (e.g., 2024-12-18, 2025-04-15)
3. Existing accounts continue receiving the old behavior without any client changes
4. Developers can test new versions by sending the Stripe-Version header
5. The Stripe dashboard shows available upgrades with detailed changelogs and migration guides
6. Most changes are additive (new fields, new endpoints) and do not require version bumps

Why it works:

This eliminates the most painful aspect of versioning: forcing clients to change. A Stripe integration built in 2020 still works in 2026 without modification. When a developer is ready to upgrade, they can test the new version per-request, review the changelog, and upgrade their account version in the dashboard.

Why most teams cannot adopt it:

Stripe maintains internal compatibility layers that translate between every active API version and the current internal data model. This is enormous engineering investment. Each "version" is essentially a response transformer that converts the internal representation to the format expected by that version. With dozens of active versions, this becomes a significant maintenance burden that only well-resourced engineering teams can sustain.

---

Real-World Examples

Company	Primary Strategy	Format	Notes
Stripe	Date-based pinning	Stripe-Version: 2024-12-18	Account-level pinning, additive-only changes
GitHub	URL + Header	/v3, Accept: application/vnd.github.v3+json	Header for preview features and media types
Twilio	URL (date-based)	/2010-04-01/Accounts	Date in URL instead of version number
Google Cloud	URL path	/v1/projects, /v2/projects	Major version in URL, minor versions additive
Microsoft Graph	URL path	/v1.0/me, /beta/me	Stable and beta channels
Slack	Flat methods	/api/conversations.list	Method-based, no explicit versioning
Twitter/X	URL path	/2/tweets	Major version in URL
Salesforce	URL path	/services/data/v59.0/	Numeric versions, long support windows

---

Breaking vs Non-Breaking Changes

Your versioning frequency is determined by how often you introduce breaking changes. Investing in non-breaking change patterns reduces the need for new versions.

Breaking changes (require a new version):

• Removing or renaming a response field
• Changing a field's data type (string to integer, object to array)
• Removing an endpoint
• Adding a required request parameter
• Changing authentication methods
• Altering error response structure

Non-breaking changes (safe without versioning):

• Adding a new optional field to responses
• Adding a new endpoint
• Adding an optional request parameter
• Adding a new enum value to an existing field
• Improving error messages while keeping error codes stable
• Increasing rate limits

Deprecation and Sunset Policies

Regardless of versioning strategy, every API needs a deprecation policy.

Sunset Header (RFC 8594):

Sunset: Sat, 08 Mar 2027 00:00:00 GMT
Deprecation: Sat, 08 Mar 2026 00:00:00 GMT
Link: <https://api.example.com/docs/migration-v3>; rel="sunset"

Industry-standard deprecation timelines:

• Stripe: 12+ months notice, all versions supported indefinitely with account pinning
• Google: 12 months minimum for GA features, 1 year deprecation period
• GitHub: Preview features can change without notice, stable APIs follow deprecation schedule
• Twilio: Major versions supported for years, deprecation announced via email and changelog

Best practices for deprecation:

1. Announce deprecation with a specific sunset date
2. Include Sunset and Deprecation headers in responses
3. Monitor usage of deprecated features by API key
4. Send targeted notifications to active users of deprecated endpoints
5. Provide migration guides with before/after code examples
6. Support the old version for at least 12 months after deprecation announcement

---

How to Choose

Use URL path versioning when:

• Building a public API consumed by external developers
• You need maximum discoverability and testability
• Your infrastructure routes on URL paths (most do)
• You want simple documentation with one spec per version

Use header versioning when:

• Building internal APIs where consumers are sophisticated
• Different resources need to version independently
• REST compliance is a stated architectural goal
• You control both the client and server

Use query parameter versioning when:

• You need a quick escape hatch during a migration
• The API is internal and short-lived
• You are adding versioning retroactively to an unversioned API

Use content negotiation when:

• Your consumers understand HTTP content negotiation
• You need fine-grained, per-resource versioning
• The API is internal with controlled client development

Use date-based version pinning when:

• You can invest in version compatibility infrastructure
• Client stability is your top priority
• Most of your changes are additive
• You have engineering resources to maintain transformation layers

---

Methodology

This comparison is based on analysis of public API documentation from Stripe, GitHub, Twilio, Google Cloud, Microsoft Graph, Slack, Twitter/X, and Salesforce. We evaluated each strategy across visibility, implementation complexity, cacheability, REST compliance, tooling support, and real-world adoption. Breaking change classification follows the OpenAPI specification's compatibility guidelines.

---

Designing your API versioning strategy? Explore API design guides and comparisons on APIScout — architecture patterns, real-world examples, and developer resources for building APIs that last.

Related: API Caching Strategies: HTTP to Redis 2026, API Changelog & Versioning Communication 2026, API Testing Strategies for 2026