api-versioning

# API Versioning

Strategies for versioning APIs, managing breaking changes, and deprecating old versions gracefully.

## When to Use This Skill

- Choosing an API versioning strategy
- Planning for breaking changes
- Deprecating API versions
- Managing multiple API versions
- Designing for API evolution

## Why Version APIs?

```text
APIs are contracts with clients.
Breaking changes break clients.

Without versioning:
- Change field name → All clients break
- Remove endpoint → All clients break
- Change behavior → Unexpected client behavior

With versioning:
- Old clients use old version
- New clients use new version
- Gradual migration possible
```

## Versioning Strategies

### URL Path Versioning

```text
https://api.example.com/v1/users
https://api.example.com/v2/users

Pros:
- Clear and explicit
- Easy to understand
- Easy to route
- Easy to cache

Cons:
- Version embedded in client code
- Multiple URLs for same resource
- Not truly RESTful (URL should identify resource)
```

### Header Versioning

```text
GET /users
Accept: application/vnd.example.v1+json

or custom header:
GET /users
API-Version: 1

Pros:
- Clean URLs
- More RESTful
- Version separate from resource

Cons:
- Hidden from URL
- Harder to test in browser
- Requires header support
```

### Query Parameter Versioning

```text
GET /users?version=1
GET /users?api-version=2023-01-01

Pros:
- Easy to add
- Optional (can default)
- Easy to test

Cons:
- Can be forgotten
- Pollutes query string
- Caching complexity
```

### Content Negotiation

```text
Accept: application/vnd.example+json; version=1

Pros:
- Standard HTTP mechanism
- Flexible

Cons:
- Complex to implement
- Hard to discover
```

## Strategy Comparison

| Strategy | Visibility | Implementation | Caching | Recommendation |
| -------- | ---------- | -------------- | ------- | -------------- |
| URL Path | High | Easy | Easy | Best for public APIs |
| Header | Low | Medium | Medium | Good for internal APIs |
| Query Param | Medium | Easy |