Api versioning strategy

Skill secondsky/claude-skills/plugins/api-versioning-strategy/skills/api-versioning-strategy

Production-ready skills for Claude Code CLI - Cloudflare, React, Tailwind v4, and AI integrations

Install

npx -y skills add secondsky/claude-skills --skill api-versioning-strategy

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

What its author says it does

Copied from the file, not written here

Implements API versioning using URL paths, headers, or query parameters with backward compatibility and deprecation strategies. Use when managing multiple API versions, planning breaking changes, or designing migration paths.

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

2.1 KB, as published. Nobody here has run it

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)

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

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

Version Adapter Pattern

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

Deprecation Headers

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