Michael Schiemer
55a330b223
- Add DISCOVERY_LOG_LEVEL=debug - Add DISCOVERY_SHOW_PROGRESS=true - Temporary changes for debugging InitializerProcessor fixes on production
295 lines
6.9 KiB
Markdown
295 lines
6.9 KiB
Markdown
# 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 |