API Versioning¶

This API uses header-based versioning to maintain backward compatibility while allowing for API evolution. The version is specified using the Accept header.

Available Versions¶

• Version 1.0 (Default): Basic data structure
• Version 2.0: Enhanced data structure with better organization

How to Specify Version¶

Include the version in the Accept header of your request:

# Version 1.0
curl -H "Accept: application/json; version=1.0" https://api.example.com/api/users/1/

# Version 2.0
curl -H "Accept: application/json; version=2.0" https://api.example.com/api/users/1/

If no version is specified, the API defaults to version 1.0.

Version Differences¶

User Endpoint¶

Version 1.0¶

Basic flat structure with all user information at the root level:

{
    "id": 1,
    "email": "user@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone_number": "1234567890",
    "address": "123 Main St",
    "date_joined": "2024-03-15T10:00:00Z",
    "is_active": true
}

Version 2.0¶

Enhanced structure with logical grouping of information:

{
    "id": 1,
    "full_name": {
        "first_name": "John",
        "last_name": "Doe",
        "display_name": "John Doe"
    },
    "account_info": {
        "email": "user@example.com",
        "date_joined": "2024-03-15T10:00:00Z",
        "is_active": true,
        "last_login": "2024-03-15T15:30:00Z"
    },
    "contact_details": {
        "phone_number": "1234567890",
        "address": "123 Main St"
    }
}

Version Lifecycle¶

1. Active Versions: Both v1.0 and v2.0 are currently active and fully supported.
2. Deprecation: When a version is planned for deprecation, warning headers will be included in responses.
3. Sunset: End-of-life dates for deprecated versions will be announced at least 6 months in advance.

Best Practices¶

1. Always specify the version in your API requests to ensure consistent behavior.
2. Monitor response headers for deprecation warnings.
3. Test your integration with both versions during development.
4. Plan to migrate to newer versions before old versions are sunset.