Sign in Get started

Decision guide

URL vs Header vs Date-Based API Versioning

How should you version an API when breaking changes are unavoidable?

Side by side

CriterionURL major versionHeader / query versionDate-pinned per accountNo versioning (evolution)
Visibility to developersHighMediumMediumN/A
Granularity of changeCoarse (majors)Per releaseFine (per change)Per field
Server complexityParallel code/infraRouting by headerVersion transformersLowest
CachingEasyNeeds VaryServer-sideEasy
Upgrade pressure on clientsBig migrationsModerateGradual, per accountContinuous
ExamplesMany public APIsAzure, GitHubStripeGraphQL APIs

When to choose each

URL major version

/v1/orders, /v2/orders.

Choose when

  • Public APIs that value visibility and simplicity
  • Rare, large breaking changes

Avoid when

  • Frequent small breaking changes
  • You can't afford parallel stacks

Header / query version

api-version=2026-10-01 or X-Api-Version header.

Choose when

  • Stable URLs with many API versions
  • Platform-wide release trains

Avoid when

  • Clients/tools that can't set headers easily
  • CDN caching without Vary

Date-pinned per account

Each account pinned to the version at signup; requests may override (Stripe).

Choose when

  • Frequent small breaking changes
  • Large customer base upgrading at its own pace

Avoid when

  • Small teams (needs transformation layers and tooling)

No versioning (evolution)

Only additive changes; deprecate and sunset old fields.

Choose when

  • GraphQL APIs
  • Internal APIs with known consumers
  • Strong tolerant-reader clients

Avoid when

  • Unavoidable semantic changes for external consumers

Verdict

First try not to version: additive changes, tolerant readers, deprecation with Sunset headers. When you must, pick one strategy per API platform. URL majors are simplest; date-pinned versions are the gold standard for large public APIs but need serious investment.

Learn more

Sources