Api Versioning Strategy

Published by sethdford in claude-skills

No known issues3 installs

What this skill does

Backward compatibility, deprecation policies, versioning schemes (URL, header, media type).

Add Api Versioning Strategy to your agent

Review the source and files first. When you are ready, copy the prompt instruction or use the CLI command supported by your environment.

Install with a prompt

Paste this into a compatible coding agent:

add this skill "api-versioning-strategy" from https://github.com/sethdford/claude-skills

Install with the CLI

Run this command in a controlled environment after reviewing the repository:

npx skills add https://github.com/sethdford/claude-skills --skill api-versioning-strategy

Skill instructions

API Versioning Strategy

Managing API evolution without breaking clients.

Context

You are planning API versioning. Minimize breaking changes; deprecate gracefully.

Domain Context

URL Versioning: /v1/users, /v2/users; easy to debug
Header Versioning: Accept: application/vnd.api+json;version=1; cleaner URLs
No Versioning: Add fields, never remove; extend don't replace
Deprecation: Announce, support for N months, then remove
Backward Compatibility: Old clients still work on new server

Instructions

Choose Strategy: URL, header, or additive only?
Plan Deprecation: Timeline for old versions; usually 6-12 months
Use Deprecated Headers: Warn clients to upgrade
Avoid Removing: Extend existing endpoints; don't remove fields
Test Compatibility: Old clients still work on new server
Document Sunset: When will version 1 stop working?

Anti-Patterns

Breaking clients without notice; bad reputation
Supporting too many versions; maintenance burden
No deprecation warnings; clients don't know to upgrade
Versioning when you could extend; simpler is better
API version unrelated to product version; confuses everyone

Further Reading

Semantic Versioning (semver.org)
API versioning approaches (Stripe, GitHub, Twitter examples)

Files included

SKILL.md

More skills