The Pragmatic Guide to API Versioning

API versioning is a topic that generates more philosophical debate than its complexity warrants. Teams spend significant energy arguing about URL versioning vs. header versioning vs. media type versioning when the more important questions are: do you have a versioning strategy at all, and does it give your consumers a clear upgrade path?

URL Versioning: The Pragmatic Choice

Put the version in the URL (/v1/, /v2/). It’s immediately visible in logs, easy to route at the infrastructure level, and unambiguous for consumers. The alternatives (Accept headers, custom headers, media type versioning) have theoretical elegance and practical drawbacks. URL versioning is boring and it works.

What Counts as a Breaking Change

Removing a field from a response. Changing a field’s type. Making an optional field required. Changing the semantics of an existing field. Adding a required field to request bodies. These are breaking changes that require a version bump. Adding optional response fields, adding new endpoints, and relaxing validation are non-breaking — deploy them without a version change.

The Deprecation Timeline

When you release v2, give v1 users a clear timeline for its sunset. Minimum six months for internal consumers, minimum twelve months for external consumers. Document the breaking changes. Provide a migration guide. Send notifications to API users when the sunset date approaches. The teams that skip these steps create the integrations that break unexpectedly and erode trust in their platform.