api-versioning-helper

Files (1)

• SKILL.md

SKILL.md (first lines)

# API Versioning Skill

Design sustainable versioning strategies and manage API evolution without breaking clients.

---

## Versioning Strategies Comparison

| Strategy | Example | Pros | Cons |
|----------|---------|------|------|
| **URI versioning** | `/v1/users` | Simple, visible, cacheable | URL proliferation |
| **Header versioning** | `API-Version: 2024-01` | Clean URLs | Harder to test/share |
| **Query param** | `/users?version=2` | Easy to override | Pollutes query string |
| **Accept header** | `Accept: application/vnd.api+json;v=2` | REST-pure | Complex client setup |
| **Date-based** (Stripe) | `Stripe-Version: 2023-10-16` | Fine-grained, changelog-linked | Harder to communicate |

**Recommendation**: Use URI versioning (`/v1/`, `/v2/`) for public APIs. Use date-based for SDKs that pin a version.

---

## Breaking vs Non-Breaking Changes

### Non-breaking (safe to ship without version bump)
- Adding new optional fields to responses
- Adding new optional request fields
- Adding new endpoints
- Adding new enum values (if client ignores unknowns)
- Relaxing validation rules
- Bug fixes that align with documented behavior

### Breaking (require new version)
- Removing fields from responses
- Renaming fields
- Changing field types (string → int)
- Making optional fields required
- Changing error codes or error shapes
- Removing endpoints
- Changing authentication method
- Adding required request fields
- Changing HTTP method for an endpoint

---

## Versioning Lifecycle

```
v1 ACTIVE     → v2 BETA      → v2 GA        → v1 DEPRECATED  → v1 SUNSET
              (6 months)     (12 months)     (6 month notice)  (410 Gone)
```

### Deprecation Response Header
```http
Deprecation: true
Sunset: Sat, 01 Jan 2025 00:00:00 GMT
Link: <https://api.example.com/v2/users>; rel="successor-version"
```

### Sunset Response (after deadline)
```http
HTTP/1.1 410 Gone
Content-Type: application/json

{
  "error": "version_sunset",
  "message": "API v1 was sunset on 2025-01-01. Please migrate to v2.",
  "migration_guide": "https://docs.example.com/migrations/v1-to-v2",
  "v2_endpoint": "https://api.example.com/v2/users"
}
```

---

## Version Negotiation Middleware

```python
SUPPORTED_VERSIONS = {"v1", "v2"}
DEPRECATED_VERSIONS = {"v1"}
SUNSET_VERSIONS = {}

def version_middleware(request, next_handler):
    version = extract_version(request.path)  # or from header
    
    if version in SUNSET_VERSIONS:
        return 410_response(version)
    
    if version not in SUPPORTED_VERSIONS:
        return 400_response(f"Unknown version. Supported: {SUPPORTED_VERSIONS}")
    
    response = next_handler(request)
    
    if version in DEPRECATED_VERSIONS:
        response.headers["Deprecation"] = "true"
        response.headers["Sunset"] = SUNSET_DATES[version]
    
    return response
```

---

## Field-Level Versioning (Stripe approach)

When a breaking change affects only one field, use field-level versioning instead of a full version bump:

```json
{
  "id": "user_123",
  "name": "Alice",
  "_deprecated": {
    "full_name": "Alice Smith"   // present until v3, then removed
  }
}
```

---

## Multi-Version Routing

```
GET /v1/users  →  UsersControllerV1.list()

From LambdaTest/agent-skills, MIT.

More from LambdaTest/agent-skills