Skip to content

skillBackend and APIs

API Versioning Strategy

Plans and introduces a new API version without breaking existing clients, with deprecation headers, usage tracking and a dated sunset schedule.

npx workspacetemplates add api-versioning-strategy --tool claude-code

Writes 1 file to .claude/skills/api-versioning-strategy/

.claude/skills/api-versioning-strategy/SKILL.md29 lines · 1.6 KBFile
---
name: api-versioning-strategy
description: Plans and introduces a new API version without breaking existing clients, with deprecation headers, usage tracking and a dated sunset schedule.
---

# API versioning strategy

Do not version what you can evolve. Version only what you must break.

## Steps

1. Classify the change. Safe: new optional field, new endpoint, new enum value only if clients are told to tolerate unknown ones. Breaking: removed or renamed field, changed type or meaning, new required input, stricter validation, changed status code.
2. If nothing breaks, ship it without a version and stop.
3. Pick the existing selector and stay with it. If none exists, use a URL prefix (`/v2/`) for public APIs or a date header for APIs with many small breaks.
4. Route by version at the edge of the app. Share the domain logic; put only the request and response mapping in per-version modules, so v1 is a thin adapter and not a copy of the code.
5. On the old version, send `Deprecation: true`, `Sunset: <HTTP date>` and a `Link: <migration guide>; rel="deprecation"` header.
6. Log the version, client id and route on every call so you can list who still uses the old version.
7. Write a migration note with before and after payloads for each break.
8. Propose a sunset date no earlier than the notice period the clients were promised. After the date, return 410 with the guide link.

## Rules

- Never change v1 behavior to suit v2.
- Never remove a version while traffic data shows active callers.
- Keep at most two live versions.

## Report

Breaking changes found, the selector chosen, files changed, the sunset date proposed and the clients still on the old version.

What it does

Versioning goes wrong in two ways: a new version for every small change, or a breaking change shipped quietly under the old one. This skill has the agent first decide whether a change is breaking at all, since additive changes need no new version.

When a break is unavoidable it sets up the version selector, keeps the old behavior running, adds Deprecation and Sunset headers, and measures who still calls the old version so the shutdown date is based on traffic.

Example

you › We need to change price from a string to an object in the orders API. How do we roll it out?

agent › Breaking: type change. Added /v2/orders returning price as {amount, currency}; v1 now adapts from the shared service and sends Deprecation and Sunset: Sat, 30 May 2027 headers. Per-client call counts are logged. Drafted docs/migrating-to-v2.md. Three partners still call v1 daily; listed with their keys.

Questions

URL prefix or header?
A URL prefix is easiest for public APIs, since it works in a browser and in logs. Header or date versions suit internal APIs with frequent small breaks.
How long should the old version live?
Longer than the notice you promised, and until traffic shows no active callers. The skill proposes a date from the usage data.
  • API Error Responses

    SkillBackend and APIs

    Free
  • API Pagination Design

    SkillBackend and APIs

    Free
  • Background Job Design

    SkillBackend and APIs

    Free
  • Caching Strategy

    Skillredis

    Free