Skip to main content
skill CX Codex

api-versioning-deprecation-planner — Claude Code skill: API planning

The api-versioning-deprecation-planner is a Claude Code skill for planning API version changes and client migrations. It covers releases of a new version while existing clients still rely on the old one.

MIT 264 installs ★ 64 updated 2026-01-12

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add patricio0312rev/skills --skill api-versioning-deprecation-planner -a claude-code
Open on GitHub

What api-versioning-deprecation-planner does

The skill helps compare URL, header, and query-parameter versioning, then shape a transition plan for clients. That plan can cover announcements, a period when both versions run, usage tracking, and the eventual shutdown of old endpoints. It includes templates for migration guides and client communications.

For backward compatibility, it outlines parallel versions, an adapter that converts response formats, and gradual rollout with feature flags. It also distinguishes changes that preserve compatibility from those that need a new version. Removing a response field or changing its type counts as a breaking change, so those decisions affect the release plan.

The migration guidance covers authentication, response formats, and pagination. The skill can also help draft monitoring checks and rollback steps. It fits planning for a v1-to-v2 transition where clients need time to move before v1 is disabled.

What it helps with

  • choose an API versioning approach
  • schedule the retirement of an older API version
  • write client migration steps for a new release
  • identify API changes that require a new version
  • prepare migration monitoring and rollback steps

Example prompts for the agent

  • Plan an API transition from v1 to v2, including client notices and the shutdown schedule.
  • Review these API changes and flag the ones that need a new version.
  • Draft migration steps for replacing query-parameter API keys with Bearer token authentication.

How to install api-versioning-deprecation-planner

1Skills CLI (Vercel)

npx skills add patricio0312rev/skills --skill api-versioning-deprecation-planner -a claude-code

2Manually: put the files in place

~/.claude/skills/api-versioning-deprecation-planner/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/api-versioning-deprecation-planner/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about api-versioning-deprecation-planner

How do I install api-versioning-deprecation-planner in Claude Code?

Run npx skills add patricio0312rev/skills --skill api-versioning-deprecation-planner -a claude-code. The skill file is at ~/.claude/skills/api-versioning-deprecation-planner/SKILL.md.

What does api-versioning-deprecation-planner do?

It helps plan API version changes, client migration, and the retirement of an older version. It also covers compatibility approaches and rollback planning.

Which API changes call for a new version?

Removing an endpoint, request parameter, or response field, changing a field's type, making an optional field required, or changing authentication are treated as breaking changes.

Source text

SKILL.md · MIT
---
name: api-versioning-deprecation-planner
description: Plans safe API evolution with versioning strategies, client migration guides, deprecation timelines, and backward compatibility considerations. Use for "API versioning", "deprecation planning", "API evolution", or "breaking changes".
---

# 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

```markdown
# 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

- [ ] Disable v1 endpoints
- [ ] Return 410 Gone with migration instructions
- [ ] Monitor for issues
```

## Deprecation Response Headers

```http
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Dec 2024 23:59:59 GMT
Link: <https://api.example.com/v2/users>; rel="alternate"
Warning: 299 - "This API version is deprecated. Migrate to v2 by Dec 31, 2024"
```

## Breaking vs Non-Breaking Changes

### Non-Breaking (Safe)

✅ Adding new endpoints
✅ Adding optional request parameters
✅ Adding fields to responses
✅ Adding new response status codes
✅ Making required fields optional

### Breaking (Requires New Version)

❌ Removing endpoints
❌ Removing request parameters
❌ Removing response fields
❌ Changing field types
❌ Making optional fields required
❌ Changing authentication

## Migration Guide Template

```markdown
# Migration Guide: API v1 → v2

## What's Changing

### Authentication

**v1:** API Key in query param
```

GET /api/v1/users?api_key=xxx

```

**v2:** Bearer token in header
```

GET /api/v2/users
Authorization: Bearer xxx

````

### Response Format
**v1:** Snake case
```json
{"user_id": 123, "first_name": "John"}
````

**v2:** Camel case

```json
{ "userId": 123, "firstName": "John" }
```

### Pagination

**v1:** Page-based

```
GET /api/v1/users?page=2&per_page=10
```

**v2:** Cursor-based

```
GET /api/v2/users?cursor=abc123&limit=10
```

## Step-by-Step Migration

### Step 1: Update Authentication

Replace query param auth with header-based:

```diff
- axios.get('/api/v1/users?api_key=xxx')
+ axios.get('/api/v2/users', {
+   headers: { 'Authorization': 'Bearer xxx' }
+ })
```

### Step 2: Update Response Handling

Adjust field name casing:

```diff
- const userId = data.user_id
+ const userId = data.userId
```

### Step 3: Update Pagination

Switch to cursor-based:

```diff
- const nextPage = page + 1
- fetch(`/api/v1/users?page=${nextPage}`)
+ const cursor = data.meta.next_cursor
+ fetch(`/api/v2/users?cursor=${cursor}`)
```

## Testing Your Migration

```bash
# 1. Test v2 in development
curl -H "Authorization: Bearer xxx" https://dev-api.example.com/v2/users

# 2. Run v1 and v2 side-by-side in staging
# Compare responses for consistency

# 3. Gradual rollout in production
# Route 10% → 50% → 100% traffic to v2
```

## Support Resources

- [API v2 Documentation](https://docs.example.com/v2)
- [Migration Examples Repo](https://github.com/example/v2-examples)
- [Support Channel](https://slack.example.com)

````

## Backward Compatibility Strategies

### 1. Parallel Versions
Run v1 and v2 simultaneously:
```typescript
app.use('/api/v1', v1Router);
app.use('/api/v2', v2Router);
````

### 2. Adapter Pattern

v1 calls v2 internally with adapter:

```typescript
// v1 endpoint
router.get("/api/v1/users", async (req, res) => {
  // Call v2
  const v2Response = await v2Controller.getUsers(req);

  // Adapt v2 response to v1 format
  const v1Response = adaptV2ToV1(v2Response);

  res.json(v1Response);
});
```

### 3. Feature Flags

Gradual feature rollout:

```typescript
if (req.version === "v2" && featureFlags.newPagination) {
  return cursorBasedPagination(req);
} else {
  return pageBasedPagination(req);
}
```

## Client Communication Plan

### Announcement Email Template

```
Subject: [ACTION REQUIRED] API v1 Deprecation - Migrate by Dec 31

Hi API Consumers,

We're deprecating API v1 on December 31, 2024. Please migrate to v2.

What's changing:
- Authentication: API keys → Bearer tokens
- Response format: snake_case → camelCase
- Pagination: page-based → cursor-based

Migration resources:
- Guide: https://docs.example.com/migration
- Examples: https://github.com/example/v2-examples
- Support: [email protected]

Timeline:
- Now: v2 available, v1 still works
- Oct 31: v1 will show deprecation warnings
- Dec 31: v1 will be shut down

Questions? Reply to this email.
```

## Monitoring Migration Progress

```typescript
// Track version usage
app.use((req, res, next) => {
  const version = req.path.includes('/v1') ? 'v1' : 'v2';
  metrics.increment('api.requests', { version });
  next();
});

// Dashboard metrics
- v1 requests/day: 10,000 → 5,000 → 1,000 → 0
- v2 requests/day: 0 → 5,000 → 9,000 → 10,000
- Unique v1 consumers: 50 → 25 → 5 → 0
```

## Rollback Plan

```markdown
## If Migration Goes Wrong

### Symptoms

- Spike in 5xx errors
- Client complaints
- Revenue impact

### Rollback Steps

1. Re-enable v1 endpoints
2. Update deprecation timeline
3. Communicate delay to clients
4. Fix issues in v2
5. Resume migration when stable
```

## Best Practices

1. **Announce early**: 6+ months notice
2. **Provide tools**: SDKs, migration scripts
3. **Support clients**: 1-on-1 help if needed
4. **Monitor usage**: Track who's still on v1
5. **Gradual sunset**: Don't surprise users
6. **Clear docs**: Step-by-step guides
7. **Offer grace period**: Extensions for large clients

## Output Checklist

- [ ] Versioning strategy chosen
- [ ] Deprecation timeline (6+ months)
- [ ] Migration guide written
- [ ] Breaking changes documented
- [ ] Backward compatibility plan
- [ ] Client communication drafted
- [ ] Monitoring dashboard setup
- [ ] Rollback plan documented
- [ ] Support resources prepared

© patricio0312rev · MIT · patricio0312rev/skills

Similar skills

All skills for Backend and APIs →

From the same set148

The whole set →
release-automation-builder release-automation-builder is a Claude Code skill for automating releases and package publishing. It responds to requests about versioning, changelogs, or release workflows. CX Codex +1 265installs postmortem-writer postmortem-writer turns an incident into a written postmortem: timeline, root cause, contributing factors, action items with owners. Runs as a skill inside your coding agent. CX Codex +1 265installs schema-consistency-checker schema-consistency-checker reads your tables and columns, flags names that break the agreed style, mismatched ID types, nullable critical fields and foreign keys without an index, then hands back a fix list. CX Codex +1 265installs deployment-checklist-generator deployment-checklist-generator generates deployment runbooks, pre-release checklists, smoke-test scripts, and post-launch verification plans. CX Codex +1 264installs state-ux-flow-builder The state-ux-flow-builder skill structures loading, error, empty, and success states for data-driven screens. Use it when a UI flow has several views or state transitions. CX Codex +1 264installs zustand-state-builder zustand-state-builder — a skill for managing app state with Zustand: minimal API, full TypeScript support, persistence, and devtools. Runs on Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode. CX Codex +1 264installs monorepo-ci-optimizer monorepo-ci-optimizer — a CI skill for monorepos: it works out which packages a change touches and runs builds and tests only for those. Useful when every PR runs the whole workspace. CX Codex +1 264installs coverage-strategist The coverage-strategist skill helps set test priorities and coverage goals across a project. Use it when deciding which paths need tests and which code can be left out. CX Codex +1 263installs

Project sponsors

Companies that keep this analytics open