Agent skill

api-versioning-strategy

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.

View SKILL.md on GitHub Repository
Stars 109
Forks 14

Install this agent skill to your Project

npx add-skill https://github.com/secondsky/claude-skills/tree/main/plugins/api-versioning-strategy/skills/api-versioning-strategy

SKILL.md

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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

secondsky/claude-skills

skill-name

[TODO: Write comprehensive description in third-person. Start with "This skill provides..." or "This skill should be used when..."] [TODO: Add "Use when" scenarios - specific situations where Claude should use this skill] [TODO: Add keywords - technologies, use cases, error messages that should trigger this skill]

109 14
Explore
secondsky/claude-skills

websocket-implementation

Implements real-time WebSocket communication with connection management, room-based messaging, and horizontal scaling. Use when building chat systems, live notifications, collaborative tools, or real-time dashboards.

109 14
Explore
secondsky/claude-skills

ai-sdk-ui

109 14
Explore
secondsky/claude-skills

bun-nextjs

This skill should be used when the user asks about "Next.js with Bun", "Bun and Next", "running Next.js on Bun", "Next.js development with Bun", "create-next-app with Bun", or building Next.js applications using Bun as the runtime.

109 14
Explore
secondsky/claude-skills

bun-sqlite

Use for bun:sqlite, SQLite operations, prepared statements, transactions, and queries.

109 14
Explore
secondsky/claude-skills

bun-sveltekit

Use when building or running SvelteKit apps on Bun, including SSR, adapters, and Bun-specific APIs

109 14
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results