Bits of .NET

🔄 V1, V2, V3 — All Running Simultaneously

Change API = break clients. API versioning lets you run multiple versions. Old clients stay on V1, new clients use V2. No downtime.

📝 Setup Versioning

dotnet add package Asp.Versioning.Mvc
dotnet add package Asp.Versioning.Mvc.ApiExplorer

// Program.cs
builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
    options.ApiVersionReader = ApiVersionReader.Combine(
        new QueryStringApiVersionReader("api-version"),
        new HeaderApiVersionReader("api-version"),
        new MediaTypeApiVersionReader("api-version")
    );
}).AddApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
});

🎯 Version Controllers

// V1 Controller
[ApiController]
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/users")]
public class UsersV1Controller : ControllerBase
{
    [HttpGet]
    public IEnumerable Get() => _service.GetUsersV1();
}

// V2 Controller (new fields)
[ApiController]
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/users")]
public class UsersV2Controller : ControllerBase
{
    [HttpGet]
    public IEnumerable Get() => _service.GetUsersV2();
}

// Multiple versions same controller
[ApiController]
[ApiVersion("1.0")]
[ApiVersion("2.0")]
[Route("api/users")]
public class UsersController : ControllerBase
{
    [HttpGet, MapToApiVersion("1.0")]
    public UserV1 GetV1() { }
    
    [HttpGet, MapToApiVersion("2.0")]
    public UserV2 GetV2() { }
}

✅ Versioning Strategies

• URL path: /api/v1/users, /api/v2/users (most common)
• Query string: /api/users?api-version=1.0
• Header: api-version: 1.0 (clean URLs)
• Media type: Accept: application/json;version=1.0

💡 Deprecation

[ApiController]
[ApiVersion("1.0", Deprecated = true)]
[Route("api/v1/users")]
public class UsersV1Controller : ControllerBase
{
    // Returns warning header: API v1 is deprecated
}

// Response includes deprecation warning
// api-supported-versions: 1.0, 2.0
// api-deprecated-versions: 1.0