---
name: API Versioning Strategy
slug: api-versioning-strategy
category: DevOps
description: API Versioning Strategy implements versioned endpoints with backward compatibility, adapters, and deprecation headers. Use it when planning breaking changes or guiding clients through migrations.
github: "https://github.com/secondsky/claude-skills/tree/main/plugins/api-versioning-strategy/skills/api-versioning-strategy"
language: TypeScript
stars: 214
forks: 31
install: "npx degit https://github.com/secondsky/claude-skills/tree/main/plugins/api-versioning-strategy/skills/api-versioning-strategy ~/.claude/skills/api-versioning-strategy"
installs_to: ~/.claude/skills/api-versioning-strategy
source_path: plugins/api-versioning-strategy/skills/api-versioning-strategy/SKILL.md
collection_size: 24
category_size: 920
collection_url: "https://dirskills.com/collections/secondsky/claude-skills"
added: 2026-09-04T05:25:55.427Z
last_synced: 2026-09-04T05:25:55.427Z
canonical_url: "https://dirskills.com/skills/api-versioning-strategy"
---

# API Versioning Strategy

API Versioning Strategy implements versioned endpoints with backward compatibility, adapters, and deprecation headers. Use it when planning breaking changes or guiding clients through migrations.

**Install:**

```bash
npx degit https://github.com/secondsky/claude-skills/tree/main/plugins/api-versioning-strategy/skills/api-versioning-strategy ~/.claude/skills/api-versioning-strategy
```

## README

# API Versioning Strategy

Choose and implement API versioning approaches with proper deprecation timelines.

## Versioning Methods

| Method | Example | Pros | Cons |
|--------|---------|------|------|
| URL Path | `/api/v1/users` | Clear, cache-friendly | URL clutter |
| Header | `API-Version: 1` | Clean URLs | Hidden, harder to test |
| Query | `?version=1` | Easy to use | Not RESTful |

## URL Path Versioning (Recommended)

```javascript
const v1Router = require('./routes/v1');
const v2Router = require('./routes/v2');

app.use('/api/v1', v1Router);
app.use('/api/v2', v2Router);
```

## Version Adapter Pattern

```javascript
// Transform between versions
const v1ToV2 = (v1Response) => ({
  data: {
    type: 'user',
    id: v1Response.user_id,
    attributes: {
      name: v1Response.user_name,
      email: v1Response.email
    }
  }
});
```

## Deprecation Headers

```javascript
app.use('/api/v1', (req, res, next) => {
  res.setHeader('Deprecation', 'true');
  res.setHeader('Sunset', 'Sat, 01 Jun 2025 00:00:00 GMT');
  res.setHeader('Link', '</api/v2>; rel="successor-version"');
  next();
});
```

## Safe vs Breaking Changes

**Safe Changes** (no version bump):
- Adding optional fields
- Adding new endpoints
- Adding optional parameters

**Breaking Changes** (requires new version):
- Removing fields
- Changing field types
- Restructuring responses
- Removing endpoints

## Deprecation Timeline

| Phase | Duration | Actions |
|-------|----------|---------|
| Deprecated | 3 months | Add headers, docs |
| Sunset Announced | 3 months | Email users |
| Read-Only | 1 month | Disable writes |
| Shutdown | - | Return 410 Gone |

## Best Practices

- Support N-1 versions minimum
- Provide 6+ months migration window
- Include migration guides with code examples
- Monitor version usage to inform deprecation