3. Versioning

Versioning lets you introduce breaking changes without disrupting existing consumers. It is one of the most important decisions you make when designing a long-lived API.

When to Version

Not every change requires a new version. Additive changes — new endpoints, new optional fields, new response fields — are backwards compatible and do not need a version bump. Reserve a new major version for changes that break existing clients:

• Removing an endpoint or a required field
• Changing the shape of a response payload
• Altering authentication requirements
• Renaming or re-rooting resources

URL-Path Versioning

The most common and discoverable approach is to embed the version in the URL path:

GET /v1/users
GET /v2/users

This makes the version visible in logs, browser history, and documentation, and avoids reliance on custom headers that some HTTP clients handle poorly.

Keeping Previous Versions Stable

Once you publish v1, treat it as a contract. Continue to serve it without modification until every known consumer has migrated to the next version. Monitor traffic and usage metrics so you know when adoption of the new version is complete.

Planning Deprecation

Deprecation should be a gradual, well-communicated process:

1. Announce the new version and the timeline for removing the old one — aim for at least six months of overlap.
2. Document a migration guide that maps old endpoints and payloads to their new equivalents.
3. Signal deprecation in the API itself by adding a Sunset HTTP header or a deprecated flag in response metadata.
4. Monitor usage of the old version. Only retire it once traffic drops to zero or you have contacted every remaining consumer.

Rushing deprecation erodes trust. Give consumers the time and information they need to migrate cleanly.