api-versioning
SKILL.md
API Versioning Patterns
Evolve your API confidently. Version correctly, deprecate gracefully, migrate safely — without breaking existing consumers.
Versioning Strategies
Pick one strategy and apply it consistently across your entire API surface.
| Strategy | Format | Visibility | Cacheability | Best For |
|---|---|---|---|---|
| URL Path | /api/v1/users |
High | Excellent | Public APIs, third-party integrations |
| Query Param | /api/users?v=1 |
Medium | Moderate | Simple APIs, prototyping |
| Header | Accept-Version: v1 |
Low | Good | Internal APIs, coordinated consumers |
| Content Negotiation | Accept: application/vnd.api.v1+json |
Low | Good | Enterprise, strict REST compliance |