api-versioning
API versioning strategies and backward compatibility patterns. Use when user asks to "version API", "API compatibility", "breaking changes", "semantic versioning", "API evolution", "deprecation strategy", "backwards compatibility", "API migration", "version management", or mentions API lifecycle management and compatibility.
Resources
6Install
npx skillscat add 1mangesh1/dev-skills-collection/api-versioning Install via the SkillsCat registry.
SKILL.md
API Versioning & Compatibility
Strategies for managing API versions, backward compatibility, and graceful deprecation.
Versioning Approaches
URL Path Versioning
/api/v1/users
/api/v2/usersQuery Parameter Versioning
GET /api/users?version=1
GET /api/users?version=2Header Versioning
Accept: application/vnd.api+json;version=1Content Negotiation
Accept: application/vnd.myapi.v2+jsonBest Practices
- Semantic Versioning - Use MAJOR.MINOR.PATCH
- Deprecation Warnings - Include deprecation headers
- Sunset Headers - Specify when API versions expire
- Changelog - Document all changes
- Migration Guides - Help clients upgrade
- Compatibility Layer - Support multiple versions temporarily
Breaking Changes Strategy
- Plan deprecation timeline (6-12 months notice)
- Provide migration documentation
- Offer tool-assisted migration (scripts, adapters)
- Support parallel versioning
- Communicate clearly in changelogs
References
- Semantic Versioning (semver.org)
- REST API Design Guidelines
- OpenAPI/Swagger Specification
Install
npx skillscat add 1mangesh1/dev-skills-collection/api-versioning Install via the SkillsCat registry.