API Versioning in .NET 8

API versioning is essential for maintaining backward compatibility while evolving your API. In .NET 8, you can implement versioning using the Microsoft.AspNetCore.Mvc.Versioning package.

API Versioning in .NET 8

API versioning is essential for maintaining backward compatibility while evolving your API. In .NET 8, you can implement versioning using the Microsoft.AspNetCore.Mvc.Versioning package.

---

1. Why Use API Versioning?

• Backward Compatibility: Ensures old clients can still use existing endpoints while new clients can leverage updated versions.
• Incremental Changes: Allows adding new features without breaking existing functionality.
• Deprecation Strategy: You can phase out old versions systematically.

---

2. Installing API Versioning Package

To enable API versioning in your .NET 8 Web API, install the following package:

dotnet add package Microsoft.AspNetCore.Mvc.Versioning

---

3. Setting Up API Versioning

Modify Program.cs to register versioning in the Dependency Injection (DI) container:

Modify Program.cs

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Versioning;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

// Register API Versioning
builder.Services.AddApiVersioning(options =>
{
    options.ReportApiVersions = true;  // Adds API version information in response headers
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.DefaultApiVersion = new ApiVersion(1, 0); // Default API version (1.0)
    options.ApiVersionReader = new UrlSegmentApiVersionReader(); // Versioning via URL
});

var app = builder.Build();

app.UseAuthorization();
app.MapControllers();

app.Run();

---

4. Applying API Versioning to Controllers

You can apply API versioning using attributes.

Using URL Path Versioning

using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/v{version:apiVersion}/orders")]
[ApiVersion("1.0")]
public class OrdersV1Controller : ControllerBase
{
    [HttpGet]
    public IActionResult GetOrders()
    {
        return Ok(new { Message = "Orders from v1 API" });
    }
}

[ApiController]
[Route("api/v{version:apiVersion}/orders")]
[ApiVersion("2.0")]
public class OrdersV2Controller : ControllerBase
{
    [HttpGet]
    public IActionResult GetOrders()
    {
        return Ok(new { Message = "Orders from v2 API - New version!" });
    }
}

Now, you can access:

• Version 1 API: GET /api/v1/orders
• Version 2 API: GET /api/v2/orders

---

5. Other API Versioning Strategies

Besides URL versioning, you can also use:

1. Query String Versioning

Modify Program.cs:

options.ApiVersionReader = new QueryStringApiVersionReader("api-version");

Then, call the API:

• GET /api/orders?api-version=1.0
• GET /api/orders?api-version=2.0

---

2. Header-Based Versioning

Modify Program.cs:

options.ApiVersionReader = new HeaderApiVersionReader("X-API-Version");

Then, pass the version in headers:

GET /api/orders
X-API-Version: 2.0

---

6. Deprecating an API Version

You can mark an API version as deprecated using:

[ApiVersion("1.0", Deprecated = true)]

This will inform clients that version 1.0 is obsolete.

---

7. Versioning via Media Type (Content-Type)

Another approach is to specify the API version in the Accept header:

options.ApiVersionReader = new MediaTypeApiVersionReader("v");

Then, call the API with:

Accept: application/json; v=2.0

---

8. Combining Multiple Versioning Strategies

You can allow multiple versioning mechanisms:

options.ApiVersionReader = ApiVersionReader.Combine(
    new UrlSegmentApiVersionReader(),
    new QueryStringApiVersionReader("api-version"),
    new HeaderApiVersionReader("X-API-Version")
);

This allows clients to specify the version using URL, query string, or headers.

---

Conclusion

API versioning is critical for maintaining compatibility while evolving your API. In .NET 8, Microsoft.AspNetCore.Mvc.Versioning provides multiple strategies:

• URL Path (/api/v1/orders)
• Query String (?api-version=1.0)
• Header (X-API-Version: 1.0)
• Media Type (Accept: application/json; v=1.0)