URL or header versioning for a new API?

URL versioning for developer ergonomics and easy testing; header versioning if you expect frequent granular changes and have sophisticated clients. Date-based is the best long-term choice for APIs that will have many breaking changes over years, but requires the most engineering investment.

How do we know which clients still use v1?

Log the version on every request and build a dashboard by customer/API key. Before deprecating anything, look at who's still calling it — targeted outreach to the top users converts far better than blanket announcements.

Can we skip versioning if we're pre-launch?

Yes. Public API versioning is a commitment to compatibility. Before you have external users, iterate freely and document as unstable. The moment you have paying customers depending on your API, the versioning discipline should already be in place — retrofitting after breakage is much more expensive.

API Versioning: URL, Header, and Date-Based Strategies

API versioning is the practice of managing changes to a public API over time so existing clients don't break when the API evolves.

API Versioning: The Decision You Only Get to Make Once

API versioning is the discipline of evolving a public API over time without breaking existing integrations. Once external clients depend on your API, breaking changes have real cost — customer engineering time, support load, churn risk. The versioning strategy determines how you communicate change, how clients opt in to new behavior, and how long you have to maintain old behavior in parallel. Stripe, Twilio, and GitHub have public writeups worth reading before choosing.

The three common strategies

(1) URL versioning — /v1/customers, /v2/customers. Simple, explicit, easy to route. Common in REST APIs (GitHub, Twilio). Cost: v2 duplicates a lot of v1 in code unless you version internally too. (2) Header versioning — Accept: application/vnd.acme.v2+json. Cleaner URLs, but harder to test in a browser and easier for clients to forget. (3) Date-based versioning — Stripe-Version: 2024-06-20 header. Each date represents a snapshot of the entire API; clients pin to a date and receive that behavior indefinitely. More overhead for the API team but the smoothest client experience. Stripe's approach is the gold standard for high-value APIs where breakage is expensive.

Non-breaking vs. breaking changes

Non-breaking (safe under any versioning): adding new endpoints, adding optional request parameters, adding new fields to responses (if clients ignore unknown fields), adding new enum values (if clients handle unknowns gracefully), relaxing validation. Breaking: removing endpoints or fields, renaming anything, changing types, changing default behavior, tightening validation, changing pagination semantics. Discipline: default all API design to backward-compatible; treat every breaking change as a real cost requiring explicit justification, not something to do casually.

Deprecation windows

When you must break, the deprecation runway matters. Standard practice: 6-12 months for public APIs with paying customers, 3-6 months for developer-preview APIs, 30 days for internal/private-beta APIs. During the window: emit deprecation warnings in response headers (Sunset: header per RFC 8594), send targeted emails to affected accounts, publish migration guides. Never remove without notice, even from small integrations — the reputation cost of surprise breakage is disproportionate to the maintenance savings.

Client SDK strategy

Providing official SDKs (usually in TypeScript, Python, Ruby, Go, PHP) drastically reduces the pain of API changes — you can absorb complexity in the SDK layer and clients update by upgrading a dependency. But SDKs are a serious ongoing commitment: multi-language maintenance, release engineering, version compatibility matrices. Small teams often start with excellent OpenAPI specs and auto-generated SDKs, then invest in hand-crafted SDKs as scale justifies. Do not ship SDKs you can't maintain — abandoned SDKs poison developer trust.

Internal APIs are different

Between services you control, versioning can be lighter — coordinated deploys, tolerant readers, and expand-contract patterns replace formal version numbers. Public APIs need the ceremony because you can't force clients to upgrade; internal APIs can often skip it because you can. Don't apply public-API versioning discipline to internal service boundaries — the overhead won't pay for itself.

Frequently asked questions

URL or header versioning for a new API?: URL versioning for developer ergonomics and easy testing; header versioning if you expect frequent granular changes and have sophisticated clients. Date-based is the best long-term choice for APIs that will have many breaking changes over years, but requires the most engineering investment.
How do we know which clients still use v1?: Log the version on every request and build a dashboard by customer/API key. Before deprecating anything, look at who's still calling it — targeted outreach to the top users converts far better than blanket announcements.
Can we skip versioning if we're pre-launch?: Yes. Public API versioning is a commitment to compatibility. Before you have external users, iterate freely and document as unstable. The moment you have paying customers depending on your API, the versioning discipline should already be in place — retrofitting after breakage is much more expensive.