跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
设计与 UI

api-versioning-patterns

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

vibeeval · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

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

技能说明


name: api-versioning-patterns description: API versioning strategies, breaking change detection, deprecation lifecycle, and migration guides

API Versioning Patterns

Versioning Strategies

StratejiÖrnekProsCons
URL Path/v1/usersAçık, cache-friendlyURL kirliliği
HeaderAccept: application/vnd.api+json;v=2Clean URLDebug zor
Query Param/users?version=2BasitCache sorunlu
Content NegotiationAccept: application/vnd.company.v2+jsonRESTfulKarmaşı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