API Versioning Strategy

🚀 Enterprise API Versioning

API versioning ensures backward compatibility while enabling continuous innovation in the RecoAgent platform, supporting enterprise customers with long-term API stability.

🎯 Versioning Strategy

1. Semantic Versioning

• Major Versions (v1, v2, v3): Breaking changes requiring migration
• Minor Versions (v2.1, v2.2): New features with backward compatibility
• Patch Versions (v2.1.1, v2.1.2): Bug fixes and security updates

2. Version Lifecycle

• Active: Current version with full support
• Deprecated: Previous version with limited support
• Sunset: End-of-life version with migration required

🚀 API Version Configuration

1. Version Manager Setup

from recoagent.packages.api.versioning import APIVersionManager

# Initialize API version manager
api_manager = APIVersionManager(
    default_version="v2",
    supported_versions=["v1", "v2"],
    deprecated_versions=["v1"],
    sunset_versions=[]
)

# Configure version lifecycle
api_manager.configure_version_lifecycle({
    "v1": {
        "status": "deprecated",
        "deprecation_date": "2024-12-31",
        "sunset_date": "2025-06-30",
        "migration_guide": "https://docs.recoagent.com/migration/v1-to-v2"
    },
    "v2": {
        "status": "active",
        "release_date": "2024-01-01",
        "end_of_life": "2026-12-31"
    }
})

2. Version Routing

from fastapi import APIRouter
from recoagent.packages.api.versioning import versioned_router

# Create versioned routers
v1_router = versioned_router("v1", prefix="/api/v1")
v2_router = versioned_router("v2", prefix="/api/v2")

# V1 endpoints (deprecated)
@v1_router.get("/users")
async def get_users_v1():
    return {
        "users": [],
        "version": "v1",
        "deprecation_warning": "This version is deprecated. Please migrate to v2."
    }

# V2 endpoints (current)
@v2_router.get("/users")
async def get_users_v2():
    return {
        "users": [],
        "version": "v2",
        "features": ["enhanced_search", "real_time_updates"]
    }

3. Version Detection

from recoagent.packages.api.versioning import VersionDetector

# Initialize version detector
version_detector = VersionDetector(
    header_name="API-Version",
    query_param="version",
    path_param="version",
    default_version="v2"
)

# Detect version from request
def detect_api_version(request):
    version = version_detector.detect_version(request)
    
    if version not in api_manager.supported_versions:
        raise HTTPException(
            status_code=400,
            detail=f"Unsupported API version: {version}"
        )
    
    return version

📊 Version Management Features

1. Backward Compatibility

Feature	v1 Support	v2 Support	Migration Required
User Management	✅	✅	❌
Data Access	✅	✅	❌
Search API	✅	✅	❌
Real-time Updates	❌	✅	✅
GraphQL API	❌	✅	✅

2. Version Lifecycle Management

Version	Status	Support Level	End of Life
v1	Deprecated	Limited	2025-06-30
v2	Active	Full	2026-12-31
v3	Planned	N/A	TBD

3. Migration Support

Migration Path	Complexity	Timeline	Tools Available
v1 → v2	Medium	3-6 months	✅ Migration guide, SDK updates
v2 → v3	Low	1-3 months	✅ Automated migration tools

🛡️ Version Security

1. Version Validation

from recoagent.packages.api.versioning import VersionValidator

# Initialize version validator
version_validator = VersionValidator(
    allowed_versions=["v1", "v2"],
    deprecated_versions=["v1"],
    sunset_versions=[]
)

# Validate API version
def validate_api_version(version: str):
    validation_result = version_validator.validate_version(version)
    
    if not validation_result.is_valid:
        raise HTTPException(
            status_code=400,
            detail=validation_result.error_message
        )
    
    if validation_result.is_deprecated:
        return {
            "version": version,
            "status": "deprecated",
            "migration_guide": "https://docs.recoagent.com/migration"
        }
    
    return {"version": version, "status": "active"}

2. Deprecation Warnings

from recoagent.packages.api.versioning import DeprecationManager

# Initialize deprecation manager
deprecation_manager = DeprecationManager(
    warning_headers=True,
    warning_messages=True,
    migration_links=True
)

# Add deprecation warnings
@deprecation_manager.deprecate_version("v1")
async def deprecated_endpoint():
    return {
        "data": "response",
        "deprecation_warning": {
            "version": "v1",
            "status": "deprecated",
            "sunset_date": "2025-06-30",
            "migration_guide": "https://docs.recoagent.com/migration/v1-to-v2"
        }
    }

📚 Migration Guides

1. v1 to v2 Migration

Breaking Changes

# V1 API (deprecated)
GET /api/v1/users
Response: {
    "users": [...],
    "total": 100
}

# V2 API (current)
GET /api/v2/users
Response: {
    "data": [...],
    "pagination": {
        "total": 100,
        "page": 1,
        "per_page": 20
    },
    "meta": {
        "version": "v2",
        "timestamp": "2024-01-01T00:00:00Z"
    }
}

Migration Steps

1. Update API Endpoints: Change from /api/v1/ to /api/v2/
2. Update Response Handling: Handle new response structure
3. Update Authentication: Use new authentication headers
4. Test Integration: Validate all API calls work correctly

2. SDK Migration

# V1 SDK usage (deprecated)
from recoagent_sdk_v1 import RecoAgentClient

client = RecoAgentClient(api_key="sk-123", version="v1")
users = client.users.list()

# V2 SDK usage (current)
from recoagent_sdk import RecoAgentClient

client = RecoAgentClient(api_key="sk-123", version="v2")
users = client.users.list()

🎯 Version Testing

1. Version Compatibility Testing

# Test version compatibility
def test_version_compatibility():
    # Test v1 compatibility
    v1_response = test_api_call("/api/v1/users", version="v1")
    assert v1_response["version"] == "v1"
    assert "deprecation_warning" in v1_response
    
    # Test v2 compatibility
    v2_response = test_api_call("/api/v2/users", version="v2")
    assert v2_response["version"] == "v2"
    assert "features" in v2_response

2. Migration Testing

# Test migration scenarios
def test_migration_scenarios():
    # Test backward compatibility
    v1_data = {"users": [{"id": 1, "name": "John"}]}
    v2_data = migrate_v1_to_v2(v1_data)
    
    assert v2_data["data"] == v1_data["users"]
    assert "pagination" in v2_data
    assert "meta" in v2_data

🎯 Next Steps

1. Choose Versioning Strategy: Select semantic versioning approach
2. Configure Version Manager: Set up version lifecycle management
3. Implement Version Routing: Create versioned API endpoints
4. Add Deprecation Warnings: Configure deprecation notifications
5. Create Migration Guides: Document version migration paths
6. Test Version Compatibility: Validate backward compatibility

---

Manage your API evolution with enterprise-grade versioning! 🚀