Enable Discovery debug logging for production troubleshooting
- Add DISCOVERY_LOG_LEVEL=debug - Add DISCOVERY_SHOW_PROGRESS=true - Temporary changes for debugging InitializerProcessor fixes on production
This commit is contained in:
295
docs/api-versioning-examples.md
Normal file
295
docs/api-versioning-examples.md
Normal file
@@ -0,0 +1,295 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user