api-versioning-helper
Installation
SKILL.md
API Versioning Skill
Design sustainable versioning strategies and manage API evolution without breaking clients.
Versioning Strategies Comparison
| Strategy | Example | Pros | Cons |
|---|---|---|---|
| URI versioning | /v1/users |
Simple, visible, cacheable | URL proliferation |
| Header versioning | API-Version: 2024-01 |
Clean URLs | Harder to test/share |
| Query param | /users?version=2 |
Easy to override | Pollutes query string |
| Accept header | Accept: application/vnd.api+json;v=2 |
REST-pure | Complex client setup |
| Date-based (Stripe) | Stripe-Version: 2023-10-16 |
Fine-grained, changelog-linked | Harder to communicate |
Recommendation: Use URI versioning (/v1/, /v2/) for public APIs. Use date-based for SDKs that pin a version.