API Versioning Strategies: URL, Header, or No Version at All

The moment a second team, a mobile app, or a paying customer starts calling your REST API, you lose the right to change it casually. Every field you rename is somebody's broken production deploy. API versioning is how you keep evolving anyway, and the industry has settled into a handful of strategies: version in the URL, version in a header, date-pinned versions per account, or the quietly radical option of never versioning and only making additive changes.

I have shipped all of these across ERP integrations and public-facing backends, and the differences are not academic; they decide how much pain your clients and your own codebase absorb over years. The answer up front for most small teams: design so you rarely need to break anything, use additive changes aggressively, and keep one coarse URL version as an escape hatch. Here is the full decision, with Stripe and GitHub as the reference implementations worth copying.

First, Agree on What Actually Breaks Clients

Versioning conversations go in circles until everyone shares a definition of a breaking change. The practical list is short. These break integrations:

• Removing or renaming a field, endpoint, or enum value that clients already receive or send.
• Changing a field's type or format, like a numeric ID becoming a string, or timestamps switching from epoch to ISO 8601.
• Tightening validation so previously accepted requests start failing, including making an optional parameter required.
• Changing error shapes or status codes that clients branch on, which teams forget because errors feel like an implementation detail. They are part of the contract.

Almost everything else is additive and safe: new endpoints, new optional fields in responses, new optional request parameters, new enum values where clients were told to handle unknowns. The single most valuable sentence in your API docs is the one telling consumers that new fields may appear at any time and must be ignored if unrecognized. That one rule converts a huge class of would-be breaking changes into routine releases.

The Four Strategies, Honestly Compared

Each strategy answers one question: where does the client declare which contract it expects? The table summarizes how that one choice plays out, and the snippet below shows the same request under each scheme:

# The same request under each strategy:

# 1. URL path version
GET /v2/invoices/inv_123

# 2. Header version (GitHub style)
GET /invoices/inv_123
X-GitHub-Api-Version: 2022-11-28

# 3. Date-pinned account version (Stripe style)
GET /v1/invoices/inv_123
Stripe-Version: 2024-06-20    # override the account's pinned date

# 4. Media-type version (rare in practice)
GET /invoices/inv_123
Accept: application/vnd.myapp.v2+json

How Stripe Makes Breaking Changes Without Breaking Anyone

Stripe's model, described in their engineering blog, is the gold standard for public APIs with long-tail integrations. Versions are rolling and named by release date. Each account is pinned to the version current at its first request, and stays there until it explicitly upgrades. Internally, every backwards-incompatible change is encapsulated in a version change module that knows how to transform a current response into the older shape.

Requests from an account pinned three years back pass through the stack once at the current version, then walk back through each transformation module until the response matches what that account expects. The genius is in the constraint: version logic lives in declarative, self-documenting modules instead of conditionals scattered through business code. The price is real engineering investment, which is exactly why you should admire this model and probably not adopt it before you have Stripe-scale backwards-compatibility obligations.

GitHub's Header-Based Calendar Versioning

GitHub's REST API takes the lighter-weight cousin of the same idea. Clients send a version header with a date value, like the 2022-11-28 version named in their docs, and requests without the header default to that baseline version so existing integrations keep working. Breaking changes ship only in new dated versions, additive changes flow into all supported versions, and GitHub commits to at least 24 months of support for each version with deprecation notice before sunset. For API producers the lesson is the policy, not the header: name your contract, default it sensibly, and publish a support window so clients can plan instead of fear.

The Underrated Option: Evolve Without Versions

For internal APIs, and for most B2B systems where you know every consumer, the strongest strategy is designing so versions are rarely needed. The toolkit is the expand-and-contract migration, applied to contracts instead of database schemas:

• Expand: add the new field or endpoint alongside the old one. Ship clients that read the new shape while the old one still flows.
• Migrate: move consumers over one by one, with logging or metrics on old-shape usage so you know exactly who is left, measured rather than guessed.
• Contract: remove the old field only when telemetry shows zero usage for a defined period. In our ERP work that period is one full month-end close, because finance flows that run monthly are where stale clients hide.
• Document the compatibility rules: clients must ignore unknown fields, never depend on key order, and treat enums as open sets. Enforce it in your own SDKs so the rule is tested, not aspirational.

What I Recommend for a Small Team

If you run a backend consumed by a handful of known clients, here is the playbook that has aged well across my projects:

1. Put a single coarse version in the URL from day one, a v1 prefix, even if you never bump it. It costs nothing now and gives you a clean escape hatch, far cheaper than retrofitting versioning under pressure later.
2. Adopt additive-only evolution as the default. Treat any breaking change as a design failure to be argued for, not a routine tool. Most weeks, the additive option exists and is only slightly less elegant.
3. Publish the unknown-fields rule and an explicit deprecation policy, even a modest one like 90 days notice. Predictability matters more to integrators than generosity.
4. Only reach for header or date-based schemes when you have real external customers whose deploy cycles you cannot see. That is the point where GitHub-style calendar versioning with a default becomes worth its operational cost.

Versioning Is a Promise-Management Problem

Strip away the mechanics and API versioning is just promise management: deciding which behaviors you guarantee, to whom, and for how long. URL versions make the promise loud and coarse, headers make it precise and quiet, Stripe's date pinning makes it eternal and expensive, and additive-only evolution avoids re-promising altogether. The takeaway: spend your discipline on not breaking contracts, instrument deprecated usage so retirement is data-driven, and keep one cheap version lever for the day you truly need it. The best version of your API is the one clients never had to think about.