api-versioning
2
总安装量
2
周安装量
#67351
全站排名
安装命令
npx skills add https://github.com/1mangesh1/dev-skills-collection --skill api-versioning
Agent 安装分布
opencode
2
claude-code
2
github-copilot
2
codex
2
kimi-cli
2
gemini-cli
2
Skill 文档
API Versioning & Compatibility
Strategies for managing API versions, backward compatibility, and graceful deprecation.
Versioning Approaches
URL Path Versioning
/api/v1/users
/api/v2/users
Query Parameter Versioning
GET /api/users?version=1
GET /api/users?version=2
Header Versioning
Accept: application/vnd.api+json;version=1
Content Negotiation
Accept: application/vnd.myapi.v2+json
Best 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