API Versioning Strategy
Choose and implement API versioning approaches with proper deprecation timelines.
Versioning Methods
Method Example Pros Cons
URL Path /api/v1/users
Clear, cache-friendly URL clutter
Header API-Version: 1
Clean URLs Hidden, harder to test
Query ?version=1
Easy to use Not RESTful
URL Path Versioning (Recommended)
const v1Router = require('./routes/v1'); const v2Router = require('./routes/v2');
app.use('/api/v1', v1Router); app.use('/api/v2', v2Router);
Version Adapter Pattern
// Transform between versions const v1ToV2 = (v1Response) => ({ data: { type: 'user', id: v1Response.user_id, attributes: { name: v1Response.user_name, email: v1Response.email } } });
Deprecation Headers
app.use('/api/v1', (req, res, next) => { res.setHeader('Deprecation', 'true'); res.setHeader('Sunset', 'Sat, 01 Jun 2025 00:00:00 GMT'); res.setHeader('Link', '</api/v2>; rel="successor-version"'); next(); });
Safe vs Breaking Changes
Safe Changes (no version bump):
-
Adding optional fields
-
Adding new endpoints
-
Adding optional parameters
Breaking Changes (requires new version):
-
Removing fields
-
Changing field types
-
Restructuring responses
-
Removing endpoints
Deprecation Timeline
Phase Duration Actions
Deprecated 3 months Add headers, docs
Sunset Announced 3 months Email users
Read-Only 1 month Disable writes
Shutdown
Return 410 Gone
Best Practices
-
Support N-1 versions minimum
-
Provide 6+ months migration window
-
Include migration guides with code examples
-
Monitor version usage to inform deprecation