API Versioning and Deprecation Strategy

You are an API architect who manages API lifecycles. Design an API versioning and deprecation strategy.

API type: [REST / GRAPHQL / GRPC]
Current state: [V1 ONLY / MULTIPLE VERSIONS]
Clients: [INTERNAL / EXTERNAL / BOTH]
Breaking change frequency: [RARE / OCCASIONAL / FREQUENT]
Client update control: [HIGH / LOW]

Provide:

**Versioning Strategy**

Recommended approach: [URL / HEADER / QUERY PARAM]
- Rationale:
- Trade-offs:

```
# URL versioning
GET /api/v1/users
GET /api/v2/users

# Header versioning
GET /api/users
API-Version: 2023-01-01

# Query param versioning
GET /api/users?version=2
```

**Version Lifecycle**
```
Beta (6 months) → GA (18 months) → Deprecated (6 months) → Sunset
```

| Version | Status | Release Date | Deprecation Date | Sunset Date |
|---------|--------|--------------|------------------|-------------|
| v1 | Deprecated | 2022-01-01 | 2024-01-01 | 2024-07-01 |
| v2 | Current | 2023-06-01 | - | - |
| v3 | Beta | 2024-01-01 | - | - |

**Breaking vs Non-Breaking Changes**

Breaking (requires new version):
- Removing fields
- Changing field types
- Changing authentication
- Removing endpoints

Non-Breaking (same version):
- Adding fields
- Adding endpoints
- Adding optional parameters
- Performance improvements

**Deprecation Process**

1. **Announce** (6 months before)
   - Blog post
   - Email to API consumers
   - In-API deprecation headers

2. **Warn** (ongoing)
```
Deprecation: true
Sunset: Sat, 01 Jul 2024 00:00:00 GMT
Link: <https://api.example.com/docs/migration>; rel="deprecation"
```

3. **Monitor** (during deprecation)
   - Track usage of deprecated endpoints
   - Identify stragglers
   - Targeted outreach

4. **Sunset**
   - Return 410 Gone
   - Helpful error message with migration info

**Migration Support**
- Migration guide template
- Changelog format
- SDK updates
- Deprecation warnings in SDKs

**Code Implementation**
```[language]
// Version routing
// Deprecation middleware
// Sunset response handler
```

**Documentation**
- Version comparison
- Migration guides
- Changelog

You are an API architect who manages API lifecycles. Design an API versioning and deprecation strategy.

API type: [REST / GRAPHQL / GRPC]
Current state: [V1 ONLY / MULTIPLE VERSIONS]
Clients: [INTERNAL / EXTERNAL / BOTH]
Breaking change frequency: [RARE / OCCASIONAL / FREQUENT]
Client update control: [HIGH / LOW]

Provide:

**Versioning Strategy**

Recommended approach: [URL / HEADER / QUERY PARAM]
- Rationale:
- Trade-offs:

```
# URL versioning
GET /api/v1/users
GET /api/v2/users

# Header versioning
GET /api/users
API-Version: 2023-01-01

# Query param versioning
GET /api/users?version=2
```

**Version Lifecycle**
```
Beta (6 months) → GA (18 months) → Deprecated (6 months) → Sunset
```

| Version | Status | Release Date | Deprecation Date | Sunset Date |
|---------|--------|--------------|------------------|-------------|
| v1 | Deprecated | 2022-01-01 | 2024-01-01 | 2024-07-01 |
| v2 | Current | 2023-06-01 | - | - |
| v3 | Beta | 2024-01-01 | - | - |

**Breaking vs Non-Breaking Changes**

Breaking (requires new version):
- Removing fields
- Changing field types
- Changing authentication
- Removing endpoints

Non-Breaking (same version):
- Adding fields
- Adding endpoints
- Adding optional parameters
- Performance improvements

**Deprecation Process**

1. **Announce** (6 months before)
   - Blog post
   - Email to API consumers
   - In-API deprecation headers

2. **Warn** (ongoing)
```
Deprecation: true
Sunset: Sat, 01 Jul 2024 00:00:00 GMT
Link: <https://api.example.com/docs/migration>; rel="deprecation"
```

3. **Monitor** (during deprecation)
   - Track usage of deprecated endpoints
   - Identify stragglers
   - Targeted outreach

4. **Sunset**
   - Return 410 Gone
   - Helpful error message with migration info

**Migration Support**
- Migration guide template
- Changelog format
- SDK updates
- Deprecation warnings in SDKs

**Code Implementation**
```[language]
// Version routing
// Deprecation middleware
// Sunset response handler
```

**Documentation**
- Version comparison
- Migration guides
- Changelog