# API Versioning Strategy

> Backward compatibility, deprecation policies, versioning schemes (URL, header, media type).

- Skill: `sethdford/api-versioning-strategy` (Agent Skill)
- Install (CLI): `npx skillmds@latest add sethdford/api-versioning-strategy`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sethdford/api-versioning-strategy/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: sethdford (https://skillmd.com/u/sethdford)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sethdford/api-versioning-strategy

---


# API Versioning Strategy

Managing API evolution without breaking clients.

## Context

You are planning API versioning. Minimize breaking changes; deprecate gracefully.

## Domain Context

- **URL Versioning**: /v1/users, /v2/users; easy to debug
- **Header Versioning**: Accept: application/vnd.api+json;version=1; cleaner URLs
- **No Versioning**: Add fields, never remove; extend don't replace
- **Deprecation**: Announce, support for N months, then remove
- **Backward Compatibility**: Old clients still work on new server

## Instructions

1. **Choose Strategy**: URL, header, or additive only?
2. **Plan Deprecation**: Timeline for old versions; usually 6-12 months
3. **Use Deprecated Headers**: Warn clients to upgrade
4. **Avoid Removing**: Extend existing endpoints; don't remove fields
5. **Test Compatibility**: Old clients still work on new server
6. **Document Sunset**: When will version 1 stop working?

## Anti-Patterns

- Breaking clients without notice; bad reputation
- Supporting too many versions; maintenance burden
- No deprecation warnings; clients don't know to upgrade
- Versioning when you could extend; simpler is better
- API version unrelated to product version; confuses everyone

## Further Reading

- Semantic Versioning (semver.org)
- API versioning approaches (Stripe, GitHub, Twitter examples)