Api Versioning Strategy

This gives you the three main API versioning approaches with actual implementation code: URL path versioning (the recommended default), header-based, and query parameters. The version adapter pattern is handy for translating between formats, and there's a solid deprecation workflow with proper HTTP headers like Sunset and successor-version links. The best part is the practical guidance on what counts as a breaking change versus a safe one, plus a realistic 7-month deprecation timeline. If you're spinning up a new API or finally dealing with that v1 you've been maintaining for three years, this covers the decision points and gives you copy-paste starting code for Express routes.

skills.sh installs: 410
GitHub stars: 248
last updated: Aug 21, 2026

View on GitHub

Install

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

Installs into .claude/skills of the current project.

Files

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();
});