api-versioning-patterns
API versioning strategies, breaking change detection, deprecation lifecycle, and migration guides
Quellinformationen
- Repository
- vibeeval/vibecosystem
- Letzte Quellaktivität
- 12. April 2026 um 23:35
- Erkannte Sprache von SKILL.md
- Türkisch
- Sterne
- 537
- Forks
- 44
Installationsoptionen
Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.
Quelldateien prüfen
Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.
SKILL.md wird angezeigt
SKILL.md
Quellanweisungen · Schreibgeschützte Vorschau- name
- api-versioning-patterns
- description
- API versioning strategies, breaking change detection, deprecation lifecycle, and migration guides
# 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
```typescript
// 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
```markdown
# 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
Auf GitHub ansehen