Chapter 11: API Versioning

Overview of API Versioning:
API versioning is a crucial aspect of building robust and scalable APIs. It allows you to introduce breaking changes, add new features, and maintain backward compatibility without disrupting existing clients. API versioning can be implemented using various strategies, including URL routing, query parameters, and headers.

Implementing API Versioning with Microsoft.AspNetCore.Mvc.Versioning:
In ASP.NET Core, you can leverage the Microsoft.AspNetCore.Mvc.Versioning package to implement API versioning. This package provides a set of features and middleware that simplify the versioning process.

Versioning through URL Routing, Query Parameters, and Headers:
API versioning can be achieved through different mechanisms. The most common ones include:

1. URL Routing: You can include the version number in the URL itself. For example, /api/v1/products and /api/v2/products represent different versions of the “products” endpoint.
2. Query Parameters: The version number can be passed as a query parameter. For instance, /api/products?version=1 and /api/products?version=2 indicate different versions of the “products” endpoint.
3. Headers: The version can also be specified in the HTTP headers, such as the Accept header or a custom header. This approach allows for more flexibility and avoids cluttering the URL.

Handling Breaking Changes and Maintaining Backward Compatibility:
As you evolve your API and introduce new versions, it’s essential to handle breaking changes carefully. Some strategies to maintain backward compatibility include:

1. Use Semantic Versioning: Follow semantic versioning principles to indicate the impact of changes on client compatibility. Increment the major version for breaking changes, minor version for new features, and patch version for bug fixes.
2. Deprecation and Sunset Policies: Clearly communicate deprecation timelines and sunset policies to allow clients to transition to newer versions smoothly.
3. Version Negotiation: Implement mechanisms for clients to negotiate the API version they want to consume. This can be done using request headers, query parameters, or other custom mechanisms.

Documenting and Testing Different API Versions:
API documentation plays a vital role in assisting clients in understanding and consuming different API versions. Tools like Swagger/OpenAPI can help generate comprehensive documentation for each version, including endpoint details, request/response models, and parameters. Additionally, thorough testing of each API version ensures its correctness and compatibility with clients.

Code Implementation:

// Startup.cs

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Versioning;
using Microsoft.Extensions.DependencyInjection;

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddControllers();

        services.AddApiVersioning(options =>
        {
            options.DefaultApiVersion = new ApiVersion(1, 0);
            options.AssumeDefaultVersionWhenUnspecified = true;
            options.ReportApiVersions = true;
        });

        services.AddVersionedApiExplorer(options =>
        {
            options.GroupNameFormat = "'v'VVV";
            options.SubstituteApiVersionInUrl = true;
        });
    }

    public void Configure(IApplicationBuilder app)
    {
        app.UseRouting();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllers();
        });
    }
}

// ProductsController.cs

using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/v{version:apiVersion}/products")]
public class ProductsController : ControllerBase
{
    // GET api/v1/products
    [HttpGet]
    [MapToApiVersion(1, 0)]
    public IActionResult GetV1()
    {
        // Logic for version 1
        return Ok("Version 1");


    }

    // GET api/v2/products
    [HttpGet]
    [MapToApiVersion(2, 0)]
    public IActionResult GetV2()
    {
        // Logic for version 2
        return Ok("Version 2");
    }
}

In this code example, we first configure API versioning in the ConfigureServices method of the Startup.cs file. We set the default API version to 1.0 and enable assuming the default version when unspecified. Additionally, we configure the reporting of API versions and the versioned API explorer to substitute the version in the URL.

Next, we implement versioned API controllers using the ProductsController as an example. The Route attribute is used to specify the route template with the version placeholder. The HttpGet attribute combined with the MapToApiVersion attribute allows mapping specific actions to different versions. In this case, we have separate actions for version 1 and version 2 of the “products” endpoint.

By following this code example, you can implement API versioning in your ASP.NET Core application using URL routing. The provided code showcases versioning through different versions of the “products” endpoint. Remember to customize the code according to your specific API requirements and business logic.