# Api Versioning Patterns

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

- **Type:** Skill
- **Install:** `agentstack add skill-vibeeval-vibecosystem-api-versioning-patterns`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [vibeeval](https://agentstack.voostack.com/s/vibeeval)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [vibeeval](https://github.com/vibeeval)
- **Source:** https://github.com/vibeeval/vibecosystem/tree/main/skills/api-versioning-patterns

## Install

```sh
agentstack add skill-vibeeval-vibecosystem-api-versioning-patterns
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [vibeeval](https://github.com/vibeeval)
- **Source:** [vibeeval/vibecosystem](https://github.com/vibeeval/vibecosystem)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-vibeeval-vibecosystem-api-versioning-patterns
- Seller: https://agentstack.voostack.com/s/vibeeval
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.