Catalog My learning Blog
API Design Course: REST and GraphQL Best Practices · Phase 1 · Lesson 6 · 3 min read

API Versioning Strategies: URL vs Header

On this page
  1. Why APIs need versioning
  2. Breaking vs non-breaking API changes
  3. URL vs header vs date-based versioning
  4. Running two API versions side by side
  5. How to retire an old API version
  6. Version as rarely as possible
  7. Check yourself

Why APIs need versioning

Your order API returns "shippingAddress": "123 Main St, Springfield, 62704". You want structured fields instead. Change it in place, and every client that reads that string breaks the moment you deploy. Versioning gives old clients the old shape while new clients opt into the new one.

Breaking vs non-breaking API changes

Breaking (needs a new version):

  • Removing or renaming a field, endpoint or parameter.
  • Changing a field's type or format (string to object, seconds to milliseconds).
  • Making an optional request field required.
  • Changing the meaning of a value or the default behavior.
  • Adding a new enum value that clients may not handle (arguably breaking; document that clients must tolerate unknown values).

Non-breaking (no new version needed):

  • Adding an optional request parameter or a new response field.
  • Adding a new endpoint.
  • Relaxing validation.

Most evolution should be additive (Day 23). Versions are for the changes that can't be.

URL vs header vs date-based versioning

StrategyExampleProsCons
URL path/v2/orders/482Visible, easy to test in a browser, easy to routeThe "same" resource has several URLs
HeaderAccept: application/vnd.acme.v2+json or API-Version: 2Clean URLsHidden; harder to test and cache correctly
Date-basedStripe-Version: 2026-09-30Small, frequent changes; each account pinned to a versionMore machinery on the server
Query parameter/orders/482?api-version=2SimpleEasy to forget; mixes with filters

URL versioning (/v1) is the most common choice for public APIs because it's obvious. Date-based versioning, used by Stripe, pins each account to the version it started with; the server transforms responses for older versions, so the company can make small breaking changes often without maintaining many full API copies.

Version in the URL, in a header, or as a date; old and new versions run side by side while clients migrate.
Version in the URL, in a header, or as a date; old and new versions run side by side while clients migrate.

Running two API versions side by side

HTTP
GET /v1/orders/482
{ "id": 482, "shippingAddress": "123 Main St, Springfield, 62704" }

GET /v2/orders/482
{ "id": 482, "shippingAddress": {
    "line1": "123 Main St", "city": "Springfield", "postalCode": "62704" } }

Keep one implementation and one data model internally, with a thin translation layer per version, rather than copying the whole codebase. The v1 adapter formats the structured address back into a string:

JavaScript
// one internal model, a thin adapter per version
const toV2 = (order) => order;
const toV1 = (order) => ({
  ...order,
  shippingAddress: [order.shippingAddress.line1, order.shippingAddress.city,
                    order.shippingAddress.postalCode].join(', '),
});

Run on the same stored order, toV1 produces exactly the v1 response above and toV2 the v2 one. A bug fix in how orders are loaded now reaches both versions at once.

How to retire an old API version

  1. Announce a deprecation date and a sunset date, with a migration guide.
  2. Send Deprecation and Sunset headers on old-version responses (Day 23).
  3. Track which clients still call v1, and contact them directly.
  4. Give generous time: months for public APIs, often a year or more.

Version as rarely as possible

Every live version is code to maintain, test and secure. Design for additive change, tolerate unknown fields in clients ("be liberal in what you accept"), and reserve new major versions for real redesigns.

Check yourself

No, as long as clients ignore fields they don't recognize, which well-written clients should. It's the most common safe change. It becomes breaking only for clients with strict schema validation that rejects unknown fields.

Each client stays on the version it integrated against while the provider ships small breaking changes frequently, transforming responses for older versions.

Bug fixes and features apply to all versions at once, and each version adds only a thin translation layer to maintain.

Removing or renaming fields, changing a field's type or meaning, adding a required request field, tightening validation, and changing status codes or error formats clients rely on.

Long enough for clients to migrate, often 6 to 12 months for public APIs, announced in advance with Deprecation and Sunset headers and usage tracking to see who's still on it.