Bits of .NET

📚 API Versioning = Smooth Evolution

APIs evolve. Versioning strategies ensure backward compatibility while allowing innovation.

📝 Versioning Strategies

# 1. URL Versioning (Most Common)
GET /api/v1/users
GET /api/v1/users/123
GET /api/v2/users
GET /api/v2/users/123

# 2. Header Versioning
GET /api/users
Accept: application/json; version=1.0
Accept: application/json; version=2.0

# 3. Query Parameter Versioning
GET /api/users?version=1
GET /api/users?version=2

# 4. Custom Header Versioning
GET /api/users
X-API-Version: 1.0
X-API-Version: 2.0

# 5. Content Negotiation
GET /api/users
Accept: application/vnd.company.v1+json
Accept: application/vnd.company.v2+json

# Implementation Example
[ApiController]
[Route(api/[controller])]
public class UsersController : ControllerBase
{
    [HttpGet]
    public IActionResult GetUsers([FromHeader] string apiVersion = 1.0)
    {
        var version = Version.Parse(apiVersion);
        
        if (version.Major == 1)
        {
            return Ok(GetUsersV1());
        }
        else if (version.Major == 2)
        {
            return Ok(GetUsersV2());
        }
        else
        {
            return BadRequest(Unsupported API version);
        }
    }
}

🎯 Deprecation Strategy

# Deprecation Headers
GET /api/v1/users
Response Headers:
Deprecation: true
Sunset: Sat, 31 Dec 2024 23:59:59 GMT
Link: ; rel=deprecation; type=text/html

# Deprecation Message
{
    data: [...],
    meta: {
        version: 1.0,
        deprecated: true,
        deprecation_date: 2024-01-01,
        sunset_date: 2024-12-31,
        migration_guide: https://docs/api/v2/migration
    }
}

# Migration Strategy
1. Announce deprecation (6-12 months before sunset)
2. Provide migration guide
3. Add warning headers
4. Encourage migration
5. Sunset old version

# Version Lifecycle
- v1.0: Active (Current)
- v2.0: In Development
- v3.0: Planning

# Release Schedule
- Every 6-12 months
- Minor updates: Weekly
- Security patches: Immediate

💡 Versioning Best Practices

• Use semantic versioning (Major.Minor.Patch)
• Deprecate with clear timeline
• Provide migration guides
• Test backward compatibility
• Monitor version adoption