Api Versioning Deprecation Planner

This handles the messy human side of API deprecation that most teams wing until they break something. You get concrete timelines (6 month templates with monthly checklists), communication templates for warning users, and clear guidelines on what counts as a breaking change versus safe evolution. The migration guide structure is solid, walking through authentication, response format, and pagination changes with before-and-after code. It covers the three main versioning approaches (URL, header, query param) with actual tradeoffs, plus monitoring snippets to track who's still hitting your old endpoints. The rollback section is honest about what to do when migrations go sideways. Good for teams shipping v2 of an API that real customers depend on.

skills.sh installs: 260
GitHub stars: 63
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add patricio0312rev/skills --skill api-versioning-deprecation-planner --agent claude-code

Installs into .claude/skills of the current project.

Files

API Versioning & Deprecation Planner

Safely evolve APIs without breaking existing clients.

Versioning Strategies

URL Versioning (Recommended)

/api/v1/users
/api/v2/users

Pros: Clear, easy to route, simple to document Cons: URL pollution with many versions

Header Versioning

GET /api/users
Accept: application/vnd.api.v1+json

Pros: Clean URLs Cons: Harder to test, less visible

Query Parameter

/api/users?version=1

Pros: Easy to implement Cons: Not RESTful, easy to forget

Deprecation Timeline

# API Deprecation Plan: v1 → v2

## Timeline (6 months)

### Month 1: Announcement

- [ ] Publish deprecation notice in changelog
- [ ] Email all API consumers
- [ ] Add deprecation headers to v1 responses
- [ ] Update documentation with migration guide

### Month 2-4: Migration Period

- [ ] v2 fully available
- [ ] Both v1 and v2 supported
- [ ] Track v1 usage metrics
- [ ] Offer migration support

### Month 5: Final Warning

- [ ] Email reminder to remaining v1 users
- [ ] Increase deprecation warning visibility
- [ ] Offer 1-on-1 migration help

### Month 6: Sunset

SKILL.md on GitHub