api-versioning-strategy
Implements API versioning using URL paths, headers, or query parameters with backward compatibility and deprecation strategies. Use when managing multiple API versions, planning breaking changes, or designing migration paths.
Install with Tessl CLI
npx tessl i github:secondsky/claude-skills --skill api-versioning-strategyOverall
score
89%
Does it follow best practices?
If you maintain this skill, you can automatically optimize it using the tessl CLI to improve its score:
npx tessl skill review --optimize ./path/to/skillValidation for skill structure
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
- Repository
- github.com/secondsky/claude-skills
- Last updated
- Created
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.