Api Versioning Strategy

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', '; 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: secondsky
• Source: secondsky/claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.