Strategy Guide

API Versioning

APIs evolve. Features get added, schemas change, and sometimes breaking changes are unavoidable. A solid versioning strategy lets you move forward without leaving your consumers behind.

Why Version Your APIs?

Every API is a contract between you and your consumers. When you change that contract — renaming a field, removing an endpoint, or altering response structures — existing integrations can break. Versioning gives you a controlled mechanism to introduce changes while maintaining backward compatibility.

The cost of breaking changes

A single unannounced breaking change can break hundreds of integrations overnight. Always version your API before introducing incompatible changes, and give consumers a clear migration timeline.

What Counts as a Breaking Change?

Not all changes require a new version. Understanding the difference is key.

Breaking

Requires a New Version

Removing or renaming an endpoint
Removing or renaming a response field
Changing an existing field's type
Adding a new required parameter
Changing authentication requirements
Altering error response formats

Non-Breaking

Safe to Ship Anytime

Adding a new optional parameter
Adding a new field to a response
Adding a new endpoint
Supporting a new content type
Improving error messages (same codes)

Versioning Strategies

There are several approaches. Each comes with trade-offs around complexity, discoverability, and developer experience.

URL Path

Header

Query Param

The most common and most visible approach. The version number is embedded directly in the URL path.

# Version 1
GET https://api.seriousmonkey.biz/v1/bananas

# Version 2
GET https://api.seriousmonkey.biz/v2/bananas

Pros: Extremely explicit, easy to understand, simple to route, works with any HTTP client.

Cons: Increases the number of URLs, can lead to large codebases if not managed carefully.

This is the approach used by Stripe, GitHub, Twilio, and most major public APIs. We recommend it for most teams.

Strategy Comparison

Strategy	Visibility	URL Cleanliness	Caching	Ease of Use
URL Path	High	Low	Excellent	Excellent
Header	Low	High	Requires config	Moderate
Query Param	Medium	Medium	Requires config	Good

Managing the Version Lifecycle

A good versioning strategy goes beyond choosing a format. You need a clear lifecycle for how versions are introduced, maintained, and eventually retired.

Version Lifecycle Phases

Active — The current recommended version. All new features and bug fixes land here first.

Maintained — Still supported. Receives critical bug fixes and security patches, but no new features.

Deprecated — Scheduled for removal. Consumers receive warnings in response headers and should migrate.

Retired — No longer available. Requests return 410 Gone with migration guidance.

Communicate Deprecation Clearly

When deprecating a version, give consumers plenty of notice and make migration easy.

# Include deprecation headers in responses
Deprecation: true
Sunset: Sat, 01 Nov 2026 00:00:00 GMT
Link: <https://docs.seriousmonkey.biz/migration/v1-to-v2>; rel="successor-version"

Pro Tip: Give at least 6 months notice before retiring a major version. Provide migration guides, tooling, and personal outreach to high-value consumers.

Best Practices

Start with v1

Don't prematurely version. Ship v1 and only create v2 when you actually have breaking changes. Over-versioning creates maintenance burden without adding value.

Use semantic intent

Keep old versions running

Automate compatibility checks

Sunset responsibly