API Versioning Strategies
API versioning, URL versioning, header versioning, backward compatibility, versioning strategy, deprecation policy, migration guide
API Versioning Strategies
APIs change over time. New features are added, old ones are improved, and sometimes breaking changes are unavoidable. API versioning allows you to introduce breaking changes without breaking existing clients. Choosing the right strategy at the start of a project prevents painful migrations later.
URL Path Versioning
The most common and explicit approach: include the version in the URL path.
app.use('/api/v1/users', v1UserRouter);
app.use('/api/v2/users', v2UserRouter);URL versioning is highly visible, easy to test in a browser, and simple to route in load balancers and API gateways. GitHub API, Stripe API, and Twitter API all use URL versioning.
What Constitutes a Breaking Change
Breaking changes require a new version: removing a field from a response, renaming a field, changing a field's data type, changing a URL path, making a previously optional parameter required, and changing authentication mechanisms. Non-breaking changes do not require a version bump: adding new optional fields, adding new endpoints, and relaxing validation constraints.
Deprecation Policy
When deprecating an old API version: announce the deprecation date publicly, send a Deprecation response header on all requests to the old version, maintain the deprecated version for at least 6-12 months, send email notifications to all registered API users, and provide a migration guide documenting every change between versions.