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