What versioning method should I choose?

URL path versioning is the recommended approach for clarity and cacheability. Headers or query parameters can work but are harder to test and may be less RESTful.

How do I communicate deprecation to clients?

Use Deprecation headers, a Sunset date, and a Link header pointing to the successor version, plus a migration guide for developers.

How long should I support old versions?

Provide an N-1 support policy with a migration window (6+ months or longer) and monitor version usage to decide when to deprecate and shut down older versions.

api-versioning-strategy

npx machina-cli add skill secondsky/claude-skills/api-versioning-strategy --openclaw

Files (1)

SKILL.md

2.1 KB

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

Source

git clone https://github.com/secondsky/claude-skills/blob/main/plugins/api-versioning-strategy/skills/api-versioning-strategy/SKILL.md

View on GitHub

Overview

Provides a structured approach to versioning your API using URL paths, headers, or query parameters. It emphasizes backward compatibility with deprecation timelines and migration paths to minimize client disruption. By supporting multiple versions concurrently, teams can plan breaking changes more safely.

How This Skill Works

Choose a versioning method (URL path, header, or query) and implement per-version routing or adapters. Use a Version Adapter Pattern to transform responses between versions. Deploy deprecation headers and a clear timeline to guide clients through migration and coexistence of versions.

When to Use It

You need to support legacy clients while introducing new features
You’re planning breaking changes and want a new version alongside the old one
You want clear, cache-friendly routes by version using URL paths
You want to emit deprecation signals (headers/links) and set sunset dates
You need to monitor version usage to determine when to deprecate old versions

Quick Start

Step 1: Decide on a method (URL path is recommended) and set up versioned routers, e.g., app.use('/api/v1', v1Router); app.use('/api/v2', v2Router)
Step 2: Implement a Version Adapter to transform older responses to the newer version if needed
Step 3: Add Deprecation headers and define a migration timeline (Deprecated → Sunset Announced → Read-Only → Shutdown) with monitoring

Best Practices

Support N-1 versions minimum
Provide a 6+ months migration window
Include migration guides with code examples
Monitor version usage to inform deprecation
Define a clear deprecation timeline with phases (Deprecated, Sunset, Read-Only, Shutdown)

Example Use Cases

URL Path Versioning: mount v1 and v2 routers (e.g., app.use('/api/v1', v1Router); app.use('/api/v2', v2Router))
Version Adapter Pattern: implement v1ToV2(v1Response) to map fields to the new shape
Deprecation Headers: set Deprecation, Sunset, and Link: '</api/v2>; rel="successor-version"'
Safe vs Breaking Changes: classify additions as safe (optional fields/endpoints) vs breaking (removed fields/restructured responses)
Deprecation Timeline: follow phases such as Deprecated, Sunset Announced, Read-Only, Shutdown with appropriate actions

Frequently Asked Questions

Add this skill to your agents