Exploring Different API Versioning Strategies in .NET 7

Introduction

API versioning is a crucial aspect of building and maintaining web APIs. It allows you to introduce changes and enhancements to your APIs without breaking existing client applications. In .NET 7, Microsoft has introduced improved ways to handle API versioning. In this article, we will explore how to organize API versions in code and explore different versioning schemes with practical examples.

Organizing API Versions In Code

In .NET 7, organizing API versions in code is made easier with Microsoft.AspNetCore.Mvc.Versioning package. This package provides attributes and conventions to version your API controllers and actions.

Step 1. Install the Versioning Package

Begin by adding the Microsoft.AspNetCore.Mvc.Versioning package to your ASP.NET Core project using NuGet Package Manager.

dotnet add package Microsoft.AspNetCore.Mvc.Versioning --version 5.0.0

Step 2. Configure API Versioning

In your Startup.cs file, configure API versioning in the ConfigureServices method.

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

    // Add other services...
}

In this example, we set the default API version to 1.0, assume the default version when not specified, and report API versions in response headers.

Step 3. Version Your Controllers

Now, let's version your controllers using attributes. Create a controller and apply the [ApiVersion] attribute.

[ApiController]
[Route("api/v{version:apiVersion}/products")]
[ApiVersion("1.0")]
[ApiVersion("2.0")]
public class ProductsController : ControllerBase
{
    // Your controller actions...
}

In this example, the ProductsController is available in both version 1.0 and 2.0 of the API.

Step 4. Implement Different Versioning Schemes

Now that you have organized your API versions in code, let's explore different versioning schemes.

URI Versioning

URI versioning involves including the version number in the URL. For example:

• /api/v1/products
• /api/v2/products

To implement URI versioning, follow the code organization steps mentioned earlier.

Header Versioning

Header versioning involves sending the version information in the HTTP request header. This approach keeps the URL clean and is often favored for larger APIs. To implement header versioning, update your controller.

[ApiController]
[Route("api/products")]
[ApiVersion("1.0")]
[ApiVersion("2.0")]
public class ProductsController : ControllerBase
{
    [HttpGet]
    [MapToApiVersion("1.0")]
    [MapToApiVersion("2.0")]
    public ActionResult<IEnumerable<string>> GetProducts()
    {
        // Your action logic...
    }
}

In this approach, the version is extracted from the query parameter, allowing clients to specify the version dynamically.

Conclusion

API versioning is a critical consideration when developing and evolving your APIs. In .NET 7, the Microsoft.AspNetCore.Mvc.Versioning package simplifies the process of organizing API versions in code. Additionally, you can choose between different versioning schemes like URI, header, or query parameter versioning, depending on your project's requirements and preferences.

By following these steps and selecting the appropriate versioning scheme, you can effectively manage API versions, ensure backward compatibility, and provide a smooth experience for your API consumers while making changes and improvements to your APIs.