api-versioning-patterns
starsforks
How to install api-versioning-patterns?
vibeeval/vibecosystem/api-versioning-patterns
$npx -y skills add vibeeval/vibecosystem --skill api-versioning-patternsAPI versioning strategies, breaking change detection, deprecation lifecycle, and migration guides
SKILL.md
| 1 | # API Versioning Patterns |
| 2 | |
| 3 | ## Versioning Strategies |
| 4 | |
| 5 | | Strateji | Örnek | Pros | Cons | |
| 6 | |----------|-------|------|------| |
| 7 | | URL Path | `/v1/users` | Açık, cache-friendly | URL kirliliği | |
| 8 | | Header | `Accept: application/vnd.api+json;v=2` | Clean URL | Debug zor | |
| 9 | | Query Param | `/users?version=2` | Basit | Cache sorunlu | |
| 10 | | Content Negotiation | `Accept: application/vnd.company.v2+json` | RESTful | Karmaşık | |
| 11 | |
| 12 | **Öneri:** URL Path (`/v1/`) — en yaygın, en anlaşılır. |
| 13 | |
| 14 | ## Breaking Change Detection |
| 15 | |
| 16 | ```typescript |
| 17 | // Breaking changes |
| 18 | const breakingChanges = [ |
| 19 | 'Required field ekleme', |
| 20 | 'Field silme veya rename', |
| 21 | 'Type değiştirme (string → number)', |
| 22 | 'Enum value silme', |
| 23 | 'Response structure değiştirme', |
| 24 | 'Error code değiştirme', |
| 25 | 'Auth requirement ekleme' |
| 26 | ] |
| 27 | |
| 28 | // Non-breaking changes |
| 29 | const nonBreaking = [ |
| 30 | 'Optional field ekleme', |
| 31 | 'Yeni endpoint ekleme', |
| 32 | 'Enum value ekleme', |
| 33 | 'Response'a optional field ekleme', |
| 34 | 'Performance improvement' |
| 35 | ] |
| 36 | ``` |
| 37 | |
| 38 | ## Deprecation Lifecycle |
| 39 | |
| 40 | ``` |
| 41 | Phase 1: ANNOUNCE (3 ay önce) |
| 42 | → Deprecation header: Sunset: Sat, 01 Jan 2027 00:00:00 GMT |
| 43 | → API docs'ta uyarı |
| 44 | → Consumer'lara email |
| 45 | |
| 46 | Phase 2: WARN (2 ay önce) |
| 47 | → Response header: Deprecation: true |
| 48 | → Log: deprecated endpoint kullanımı |
| 49 | → Dashboard: kullanım metrikleri |
| 50 | |
| 51 | Phase 3: THROTTLE (1 ay önce) |
| 52 | → Rate limit düşür |
| 53 | → Warning response body'ye ekle |
| 54 | |
| 55 | Phase 4: SUNSET |
| 56 | → 410 Gone döndür |
| 57 | → Migration guide link'i ile |
| 58 | ``` |
| 59 | |
| 60 | ## Migration Guide Template |
| 61 | |
| 62 | ```markdown |
| 63 | # Migration: v1 → v2 |
| 64 | |
| 65 | ## Breaking Changes |
| 66 | 1. `GET /v1/users` → `GET /v2/users` |
| 67 | - Response: `{ data: User[] }` → `{ items: User[], meta: {...} }` |
| 68 | 2. `POST /v1/orders` |
| 69 | - New required field: `currency` (ISO 4217) |
| 70 | |
| 71 | ## Step-by-Step |
| 72 | 1. Update client SDK to v2 |
| 73 | 2. Add `currency` field to order creation |
| 74 | 3. Update response parsing for `items` + `meta` |
| 75 | 4. Test against v2 staging |
| 76 | 5. Switch production to v2 |
| 77 | |
| 78 | ## Compatibility Period |
| 79 | v1 available until: 2027-06-01 |
| 80 | ``` |
| 81 | |
| 82 | ## Checklist |
| 83 | |
| 84 | - [ ] Versioning stratejisi seçilmiş |
| 85 | - [ ] Breaking change policy documented |
| 86 | - [ ] Deprecation lifecycle tanımlı |
| 87 | - [ ] Sunset header ekleniyor |
| 88 | - [ ] Migration guide var |
| 89 | - [ ] Version usage metrikleri tracked |
| 90 | - [ ] Consumer notification sistemi var |
| 91 | - [ ] Minimum 6 ay backward compatibility |
| 92 | |
| 93 | ## Anti-Patterns |
| 94 | |
| 95 | - Version'sız API (her değişiklik breaking) |
| 96 | - Eski version'u ani kapatma (sunset lifecycle uygula) |
| 97 | - Breaking change without version bump |
| 98 | - Her küçük değişiklikte yeni version |
| 99 | - Consumer'lara haber vermeden deprecate |
People who liked this also viewed
6 picksType
- hyperframes-cliUse the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, SkillsJul 2026
- request-refactor-planSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
- analyze-projectRigor Analyze / Rigor Audit read-only skill for deep learning research repositories. Use when the user wants to read and understand a repository, inspect model structure and training or inference entrSkillsMay 2026
- explore-codeRigor Improve implementation leaf skill for auditable candidate implementation in deep learning research repositories. Use when the researcher explicitly authorizes exploratory work on an isolated braSkillsMay 2026
- ubiquitous-languageSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
- scaffold-exercisesSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
