Every discussion about API versioning starts with best practices and ends with compromises based on what your team can actually maintain and what your customers will tolerate.

The theory is clean. The practice is messy. Here’s what actually works once you’ve got real customers depending on your API.

The Version-in-URL Approach

This is the most common approach: /api/v1/users, /api/v2/users. It’s explicit, it’s easy to understand, and it lets you run multiple versions simultaneously.

The advantage is clarity. Clients know exactly which version they’re calling. You can sunset old versions on a clear timeline. Testing is straightforward - each version is a separate endpoint.

The disadvantage is maintenance burden. You’re maintaining multiple complete API implementations simultaneously. A bug fix often needs to be applied across multiple versions. A security patch needs to go everywhere.

I’ve seen platforms running four active API versions simultaneously, with separate routing, controllers, and business logic for each. The code duplication and testing overhead was enormous.

This approach works if you have few versions active at once (1-2 max) and clear deprecation timelines. It becomes unsustainable if you accumulate versions because customers never migrate.

The Version-in-Header Approach

Instead of the URL, the API version goes in a request header: Accept: application/vnd.myapi.v2+json. The URL stays clean: /api/users.

The advantage is that URLs don’t change between versions. From a client perspective, it’s just a header change to use a different version. From an SEO or documentation perspective, there’s one URL per resource, not one per version.

The disadvantage is invisibility. Looking at request logs or API monitoring, you need to check headers to know which version was called. Debugging gets harder. Routing logic becomes more complex.

This approach works well for platforms with sophisticated API clients who understand header-based versioning. It works less well for simpler integrations or public APIs where URL-based versioning is more discoverable.

The No-Versioning Approach

Some platforms attempt to avoid versioning entirely by maintaining backward compatibility forever. Only add fields, never remove or change them. Only add endpoints, never modify existing ones.

The advantage is simplicity for clients. They integrate once, and it keeps working. No migration needed. No version-specific code.

The disadvantage is technical debt accumulation. Your API design gets constrained by every historical decision. You can’t fix mistakes without breaking compatibility. Over time, the API becomes increasingly awkward as you work around old design choices.

This approach works for APIs with simple, stable domains where the resource model doesn’t change much. It fails for complex, evolving platforms where the underlying business domain is changing.

The Incremental Version Approach

Some platforms use incremental versions for each change: 2024-03-23, 2024-06-15, 2024-09-30. Stripe does this. Each date represents a snapshot of the API at that point.

The advantage is precision. Clients can opt into specific changes rather than jumping between major versions. Breaking changes are isolated to specific version dates.

The disadvantage is complexity. You’re maintaining many version snapshots simultaneously. Clients need to understand what changed in each version to decide when to migrate.

This approach works for platforms with frequent, incremental changes and sophisticated developer audiences. It’s overkill for simpler APIs with infrequent breaking changes.

What Actually Happens at Scale

Most platforms that start with clean versioning strategies end up with hybrid approaches.

They might version major API redesigns in the URL (/v1/, /v2/) but handle minor changes through optional request parameters or feature flags. They might use date-based versioning for breaking changes but maintain backward compatibility within a version.

The pattern I see working is: version the big stuff explicitly, handle the small stuff through expansion. When you release a truly different API design, version it clearly. When you’re adding optional fields or deprecating rarely-used features, handle it within a version using warnings and gradual deprecation.

The Deprecation Problem

Versioning strategy doesn’t matter if you can’t actually deprecate old versions. And deprecation is where most platforms struggle.

You announce v1 is deprecated, give clients 12 months to migrate, extend it because major clients haven’t moved, extend it again, and end up supporting v1 indefinitely.

The platforms that successfully sunset old API versions have three things in common:

1. Clear, enforced deprecation timelines communicated early
2. Active support helping major clients migrate
3. Usage analytics showing who’s still on old versions

Without these, deprecation announcements are just noise. Customers ignore them because they know you won’t actually turn off the old version.

Migration Mechanics

How you help clients migrate between versions matters as much as the versioning scheme itself.

Good migration support includes:

• Clear changelogs showing exactly what changed
• Migration guides with code examples
• Automated tools to identify breaking changes in client code
• Sandbox environments running new versions before production cutover
• Gradual rollout options (percentage of requests to new version)

Without these, asking clients to migrate is asking them to accept significant risk and effort. Most will defer until forced.

The Version Sprawl Problem

The danger with any versioning strategy is accumulating too many supported versions. Each additional active version multiplies testing and maintenance costs.

The platforms avoiding version sprawl limit how many versions are active simultaneously. Common patterns:

• Max 2 versions active (current + previous)
• Fixed support windows (12-18 months per version)
• Automatic version bumping (clients default to latest compatible version)

This requires discipline. It means enforcing deprecation timelines even when it’s inconvenient. It means occasionally upsetting customers who haven’t migrated yet.

But the alternative is maintaining 5+ versions indefinitely, which makes any substantial platform evolution nearly impossible.

When to Version

Not every API change needs a new version. The question is: does this change break existing client code?

Adding optional fields: No version needed. Old clients ignore new fields.

Adding new endpoints: No version needed. Old clients don’t call them.

Changing required fields, removing fields, changing behavior: Version needed. This breaks existing clients.

The platforms that version too aggressively end up with version sprawl. The platforms that version too conservatively accumulate technical debt and awkward API design.

The balance is to version when you have breaking changes that materially improve the API, not for every minor modification.

Lessons from Production

URL-based versioning works well for most platforms. It’s not the most elegant solution, but it’s practical and well-understood.

Keep the number of active versions minimal - ideally 2, maximum 3. More than that becomes unmaintainable.

Invest heavily in migration support. The quality of your migration path determines whether clients actually move to new versions.

Accept that some percentage of clients will stay on old versions longer than ideal. Plan for gradual migration, not instant cutover.

API versioning is a people problem as much as a technical problem. The best versioning strategy is the one your team can maintain and your customers can navigate.