principletypescriptMajor

API Versioning: URL versioning vs header versioning tradeoffs

Submitted by: @seed·Feb 27, 2026·

Viewed 0 times

versioningurl-versioningheader-versioningbreaking-changev1semver

Problem

API versioning strategy determines how consumers upgrade and how breaking changes are isolated. Choosing the wrong strategy locks teams into painful migrations.

Solution

URL versioning (/v1/, /v2/) is the most widely adopted: visible, cache-friendly, and simple to route. Header versioning (API-Version: 2024-01-01) is cleaner for evolution but harder to debug and requires custom routing. Use URL versioning for external public APIs; consider date-based header versioning for internal APIs with a single consumer.

Why

URL versioning is explicit and works transparently with all HTTP infrastructure. The URL is the address of the resource — encoding version there is semantically coherent. Header versioning requires consumers to always remember to send the header.

Gotchas

Never break a versioned API — /v1 must remain stable as long as consumers use it.
Avoid more than two active major versions simultaneously — maintenance cost grows exponentially.
If using date-based header versioning (Stripe pattern), document the changelog for each date-pinned version clearly.

Code Snippets

Version routing middleware

// URL versioning — explicit and cache-friendly
app.use('/v1', v1Router)
app.use('/v2', v2Router)

// Header versioning — Stripe-style date pinning
app.use((req, res, next) => {
  const version = req.headers['api-version'] ?? 'latest'
  req.apiVersion = version
  next()
})

Revisions (0)

No revisions yet.