2026-09-17 · 8 min
API Versioning Strategy: URL Path vs Header vs Query String — Which One Holds in Production
You pick URL versioning on a Tuesday, ship it to production, and nine months later you’re staring at three active versions, a client who refuses to migrate off v1, and a routing layer that’s become load-bearing spaghetti. That’s the actual lifecycle of API versioning decisions — not just the initial choice, but what happens after.
This article covers the three dominant API versioning strategies — URL path, Accept header, and query string — with concrete routing configuration, the specific conditions where each breaks down, and how to structure deprecation so you’re not maintaining dead code forever.
The three strategies, honestly assessed
URL path versioning embeds the version in the URL itself:
GET /v1/payments/123
GET /v2/payments/123
This is what Stripe, Twilio, and most public APIs use. The reason is operational simplicity, not theoretical correctness. Server logs, monitoring dashboards, CDN cache keys, and reverse proxy rules all work off URLs — having the version visible there means every layer of your infrastructure can reason about it without custom header parsing. When I set up API monitoring for a fintech in Serpong last year, the first thing the SRE team asked was “can I filter by version in Datadog?” With URL versioning, that’s a single dimension on the URL field. With header versioning, you’re writing custom log parsers.
The legitimate criticism is that the URL is supposed to identify a resource. /v1/payments/123 and /v2/payments/123 are the same payment — only the representation differs. That’s what Accept headers are for.
Accept header versioning (content negotiation) uses the Accept header to specify the desired version:
GET /payments/123
Accept: application/vnd.yourapi.v2+json
This is more semantically correct per REST constraints. The URL stays stable; only the representation changes. GitHub’s API used this model. The problem is that it’s invisible to most infrastructure. Your nginx access log shows GET /payments/123 and you have no idea which version was requested without parsing the header. API gateways need explicit configuration to route on headers. Client developers — especially mobile developers — frequently get it wrong and fall back to the default version silently, creating subtle bugs that are hard to reproduce.
Query string versioning appends the version as a parameter:
GET /payments/123?version=2
This one is mostly used when the team couldn’t agree on the other two and defaulted to something quick. It works. CDN caching requires extra configuration since caches often strip or ignore query parameters. It’s also easy to accidentally omit in a fetch call and silently get the wrong version. I’d use it only for internal tools where the consumer base is small and controlled.
Routing configuration: nginx
The most common infrastructure question is how to route versioned requests to different service instances or route prefixes. Here’s a production-usable nginx config for URL path versioning with two active versions:
# nginx.conf excerpt
upstream api_v1 {
server 10.0.1.10:3000;
server 10.0.1.11:3000;
keepalive 32;
}
upstream api_v2 {
server 10.0.2.10:3000;
server 10.0.2.11:3000;
keepalive 32;
}
server {
listen 443 ssl;
server_name api.yourservice.id;
# V1 — add deprecation headers on every response
location /v1/ {
proxy_pass http://api_v1/;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
# RFC 8594 — machine-readable deprecation date
add_header Sunset "Sat, 01 Jan 2028 00:00:00 GMT" always;
add_header Deprecation "true" always;
add_header Link '<https://api.yourservice.id/v2/>; rel="successor-version"' always;
}
# V2 — current stable
location /v2/ {
proxy_pass http://api_v2/;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
# No version prefix — reject explicitly rather than silently forwarding
location / {
return 400 '{"error":"version_required","message":"Include API version in path: /v1/ or /v2/"}';
add_header Content-Type application/json;
}
}
The location / block that returns 400 is important. Without it, unversioned requests silently hit some default behavior. Make the missing version visible immediately.
For Accept header versioning, nginx routing requires the ngx_http_map_module:
map $http_accept $api_upstream {
"~*vnd\.yourapi\.v1" api_v1;
"~*vnd\.yourapi\.v2" api_v2;
default api_v2; # default to latest — document this explicitly
}
server {
location /payments {
proxy_pass http://$api_upstream;
}
}
The default line needs a documented decision: do unversioned requests get the latest, the oldest stable, or a 400? There’s no right answer, but make it explicit and put it in your API docs.
Handling versions inside the service
If you’re routing at the gateway level to separate service instances per version, the service itself doesn’t need to know its version — it’s just “the current version.” This is the cleanest pattern during major version transitions.
More commonly during early versions, you’re running both v1 and v2 in the same codebase. Here’s how to do that without duplicating entire controllers:
// Extract version from request early — middleware level
app.use((req, res, next) => {
const match = req.path.match(/^\/v(\d+)\//);
req.apiVersion = match ? parseInt(match[1], 10) : null;
if (!req.apiVersion) {
return res.status(400).json({
error: "version_required",
supported: [1, 2],
});
}
next();
});
// Route to shared handler with version context
app.get("/v:version/payments/:id", async (req, res) => {
const payment = await paymentService.getById(req.params.id);
if (req.apiVersion === 1) {
// V1 shape — legacy field names
return res.json({
payment_id: payment.id,
payment_status: payment.status,
amount_idr: payment.amount,
});
}
// V2 shape — current
return res.json({
id: payment.id,
status: payment.status,
amount: payment.amount,
currency: payment.currency,
createdAt: payment.createdAt,
});
});
The key discipline here: the business logic (paymentService.getById) is version-agnostic. Only the serialization layer differs. The moment business logic starts branching by version, you have a maintenance problem that compounds with each new endpoint.
When each strategy breaks down
URL path versioning breaks when you have fine-grained resource representations that vary independently. If /v2/payments/123 returns a payment object with a different shape than /v1/payments/123, but your /v2/users/456 endpoint is identical to /v1/users/456, you’re now maintaining routing infrastructure for a versioning boundary that doesn’t apply everywhere. Accept header versioning handles this more elegantly — each resource can evolve independently without URL proliferation.
Accept header versioning breaks when your consumers are diverse and uncontrolled. Third-party integrators, mobile apps built by external contractors, legacy ERP systems that tunnel everything through a fixed HTTP library — these clients frequently send wrong or missing Accept headers. When that happens, they get the default version silently. You only find out when they file a bug report saying “your API changed.”
Query string versioning breaks at the CDN layer. If you’re behind CloudFront or Fastly and caching GET responses, cache keys that include query parameters require explicit configuration. Without it, /payments/123?version=1 and /payments/123?version=2 may serve the same cached response to different consumers.
Deprecation that actually works
Deprecation without follow-through is just noise. The mechanics that work in practice:
- Add
SunsetandDeprecationheaders on day one of deprecation — not a week before cutoff. - Log every request to deprecated versions with client identifier (API key, JWT
subfield, IP range). Build a dashboard showing who’s still calling v1. - Email or Slack the specific client teams when their usage appears in that dashboard. Not a mass announcement — direct contact.
- Hard-cut on the announced date. Returning 410 Gone is better than silently redirecting — clients need to know they hit a dead version.
The clients who don’t migrate are not forgetting — they’re deprioritizing. A Sunset header they see in development is more persuasive than a deprecation notice they archive in email.
The decision
For a new API in 2026: URL path versioning if you have any external consumers or diverse client types. Accept header versioning if you’re building an internal API where you control all consumers and want cleaner semantics. Query string versioning for internal tooling where simplicity matters more than correctness.
The version strategy is not the hard problem. The hard problem is the discipline to treat version bumps as expensive — because they are. Every new version is a parallel maintenance surface. Before you create /v3/, spend a week checking whether a backward-compatible field addition would have covered 80% of what the new version needs to do.
Most teams version too eagerly. The APIs with the least version proliferation are the ones with the most deliberate breaking-change policy, not the ones with the most careful routing infrastructure.
Ditulis oleh Reza Pradipta