# API Versioning Examples

The API Versioning system provides flexible, clean version management with support for multiple versioning strategies.

## Supported Versioning Strategies

### 1. Header-Based Versioning (Recommended)

```bash
# Using API-Version header
curl -X GET https://localhost/api/users \
  -H "API-Version: 2.0.0" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"

# Using custom header
curl -X GET https://localhost/api/users \
  -H "X-API-Version: v2" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
```

### 2. URL Path Versioning

```bash
# Version in URL path
curl -X GET https://localhost/api/v1/users \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"

curl -X GET https://localhost/api/v2/users \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
```

### 3. Query Parameter Versioning

```bash
# Version as query parameter
curl -X GET https://localhost/api/users?version=2.0 \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
```

### 4. Accept Header Versioning

```bash
# Version in Accept header
curl -X GET https://localhost/api/users \
  -H "Accept: application/json;version=2.0" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
```

## Version Information Endpoints

### Get Current Version Info

```bash
curl -X GET https://localhost/api/version \
  -H "API-Version: 2.0.0" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
```

Response:
```json
{
  "current_version": "v2.0.0",
  "current_version_numeric": "2.0.0",
  "latest_version": "v2.0.0",
  "default_version": "v1.0.0",
  "is_latest": true,
  "is_deprecated": false,
  "supported_strategies": [
    {
      "name": "header",
      "description": "Version specified in API-Version header",
      "header_name": "API-Version"
    },
    {
      "name": "url_path",
      "description": "Version specified in URL path (/api/v1/users)",
      "header_name": "API-Version"
    }
  ]
}
```

### Get Supported Versions

```bash
curl -X GET https://localhost/api/versions \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
```

Response:
```json
{
  "supported_versions": [
    {
      "version": "v2.0.0",
      "version_numeric": "2.0.0",
      "is_default": false,
      "is_latest": true,
      "is_deprecated": false,
      "major": 2,
      "minor": 0,
      "patch": 0
    },
    {
      "version": "v1.0.0",
      "version_numeric": "1.0.0",
      "is_default": true,
      "is_latest": false,
      "is_deprecated": true,
      "major": 1,
      "minor": 0,
      "patch": 0
    }
  ],
  "total_versions": 2,
  "versioning_config": {
    "strict_versioning": false,
    "deprecation_warnings": true,
    "default_version": "v1.0.0",
    "latest_version": "v2.0.0"
  }
}
```

## API Version Differences

### Version 1.0 Response Format

```bash
curl -X GET https://localhost/api/v1/users/1 \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
```

Response:
```json
{
  "id": 1,
  "name": "User 1",
  "email": "user1@example.com",
  "created_at": "2024-01-01T00:00:00Z"
}
```

### Version 2.0 Response Format

```bash
curl -X GET https://localhost/api/v2/users/1 \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
```

Response:
```json
{
  "data": {
    "id": 1,
    "name": "User 1",
    "email": "user1@example.com",
    "profile": {
      "bio": "This is the bio for user 1",
      "avatar_url": "https://example.com/avatars/1.jpg",
      "website": "https://user1.example.com",
      "location": "San Francisco, CA",
      "verified": false
    },
    "settings": {
      "notifications": true,
      "privacy_level": "public",
      "theme": "dark"
    },
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  "meta": {
    "api_version": "2.0.0",
    "response_time_ms": 127
  }
}
```

## Deprecation Warnings

When using deprecated endpoints, you'll receive warning headers:

```bash
curl -X GET https://localhost/api/v1/users/1/profile \
  -H "API-Version: 1.0.0" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" \
  -I
```

Response Headers:
```
HTTP/1.1 200 OK
Content-Type: application/json
API-Version: v1.0.0
Warning: 299 - "This endpoint is deprecated and will be removed in v2.0.0"
```

## Migration Guide

### Get Migration Instructions

```bash
curl -X POST https://localhost/api/version/migrate \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" \
  -d '{
    "from_version": "1.0.0",
    "to_version": "2.0.0"
  }'
```

Response:
```json
{
  "from_version": "v1.0.0",
  "to_version": "v2.0.0",
  "compatible": false,
  "migration_required": true,
  "changes": {
    "breaking_changes": [
      "Response format changed to include metadata wrapper",
      "Profile endpoint moved from /users/{id}/profile to new format",
      "Error responses now include detailed validation information"
    ],
    "new_features": [
      "Enhanced user profile with social links and stats",
      "Pagination support for list endpoints",
      "Response time metadata in all responses"
    ],
    "deprecated_endpoints": [
      "/api/v1/users/{id}/profile - Use /api/v2/users/{id}/profile instead"
    ],
    "migration_steps": [
      "1. Update API version header to v2.0.0",
      "2. Update response parsing to handle metadata wrapper",
      "3. Update error handling for new error format",
      "4. Test all endpoints with new response format",
      "5. Update profile endpoint calls if used"
    ]
  },
  "estimated_effort": "Medium"
}
```

## Error Handling

### Unsupported Version (with strict versioning)

```bash
curl -X GET https://localhost/api/users \
  -H "API-Version: 3.0.0" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
```

Response:
```json
{
  "error": "Unsupported API version",
  "requested_version": "v3.0.0",
  "supported_versions": ["v1.0.0", "v2.0.0"],
  "latest_version": "v2.0.0"
}
```

## Controller Configuration

### Using ApiVersionAttribute

```php
// Class-level version constraint
#[ApiVersionAttribute('2.0.0', introducedIn: '2.0.0')]
class UsersV2Controller
{
    // All methods in this controller require v2.0+
}

// Method-level deprecation
#[Route(path: '/api/v1/users/{id}/profile', method: Method::GET)]
#[ApiVersionAttribute('1.0.0', introducedIn: '1.0.0', deprecatedIn: '1.5.0', removedIn: '2.0.0')]
public function getProfile(Request $request): HttpResponse
{
    // This method is deprecated in v1.5.0 and removed in v2.0.0
}
```

## Best Practices

1. **Use Header Versioning**: Most flexible and doesn't pollute URLs
2. **Semantic Versioning**: Use major.minor.patch format
3. **Deprecation Warnings**: Always warn before removing endpoints
4. **Migration Guides**: Provide clear migration paths
5. **Backward Compatibility**: Maintain compatibility within major versions
6. **Version Documentation**: Document changes between versions
7. **Default to Stable**: Use stable version as default, not latest