Api versioning patterns

Skill vibeeval/vibecosystem/skills/api-versioning-patterns

AI software team for Claude Code - 138 agents, 295 skills, 73 hooks. Self-learning, multi-agent swarm, autonomous skill evolution.

Install

npx -y skills add vibeeval/vibecosystem --skill api-versioning-patterns

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

What its author says it does

Copied from the file, not written here

API versioning strategies, breaking change detection, deprecation lifecycle, and migration guides

SKILL.md

2.6 KB, as published. Nobody here has run it

API Versioning Patterns

Versioning Strategies

Strateji	Örnek	Pros	Cons
URL Path	`/v1/users`	Açık, cache-friendly	URL kirliliği
Header	`Accept: application/vnd.api+json;v=2`	Clean URL	Debug zor
Query Param	`/users?version=2`	Basit	Cache sorunlu
Content Negotiation	`Accept: application/vnd.company.v2+json`	RESTful	Karmaşık

Öneri: URL Path (/v1/) — en yaygın, en anlaşılır.

Breaking Change Detection

// Breaking changes
const breakingChanges = [
  'Required field ekleme',
  'Field silme veya rename',
  'Type değiştirme (string → number)',
  'Enum value silme',
  'Response structure değiştirme',
  'Error code değiştirme',
  'Auth requirement ekleme'
]

// Non-breaking changes
const nonBreaking = [
  'Optional field ekleme',
  'Yeni endpoint ekleme',
  'Enum value ekleme',
  'Response'a optional field ekleme',
  'Performance improvement'
]

Deprecation Lifecycle

Phase 1: ANNOUNCE (3 ay önce)
  → Deprecation header: Sunset: Sat, 01 Jan 2027 00:00:00 GMT
  → API docs'ta uyarı
  → Consumer'lara email

Phase 2: WARN (2 ay önce)
  → Response header: Deprecation: true
  → Log: deprecated endpoint kullanımı
  → Dashboard: kullanım metrikleri

Phase 3: THROTTLE (1 ay önce)
  → Rate limit düşür
  → Warning response body'ye ekle

Phase 4: SUNSET
  → 410 Gone döndür
  → Migration guide link'i ile

Migration Guide Template

# Migration: v1 → v2

## Breaking Changes
1. `GET /v1/users` → `GET /v2/users`
   - Response: `{ data: User[] }` → `{ items: User[], meta: {...} }`
2. `POST /v1/orders`
   - New required field: `currency` (ISO 4217)

## Step-by-Step
1. Update client SDK to v2
2. Add `currency` field to order creation
3. Update response parsing for `items` + `meta`
4. Test against v2 staging
5. Switch production to v2

## Compatibility Period
v1 available until: 2027-06-01

Checklist

Versioning stratejisi seçilmiş
Breaking change policy documented
Deprecation lifecycle tanımlı
Sunset header ekleniyor
Migration guide var
Version usage metrikleri tracked
Consumer notification sistemi var
Minimum 6 ay backward compatibility

Anti-Patterns

Version'sız API (her değişiklik breaking)
Eski version'u ani kapatma (sunset lifecycle uygula)
Breaking change without version bump
Her küçük değişiklikte yeni version
Consumer'lara haber vermeden deprecate