Versioning is essential in API development to ensure backward compatibility and allow for incremental improvements without breaking existing clients. ASP.NET Core 8 provides robust support for API versioning through various methods. This guide covers how to implement API versioning, including URL segment versioning, query string versioning, header versioning, and best practices.

1. Introduction to API Versioning

API versioning allows you to maintain multiple versions of your API simultaneously. This is critical when making breaking changes to your API while still supporting clients using older versions.

Why Use API Versioning?

• Backward Compatibility: Ensure that existing clients can continue to use your API even after new versions are released.
• Incremental Improvements: Introduce new features and improvements in your API without disrupting existing functionality.
• Deprecation Management: Gradually phase out old versions of your API while directing users to newer versions.
• Client-Specific Needs: Allow different clients to use different versions of your API based on their specific needs.

2. Installing API Versioning

ASP.NET Core provides a package specifically for API versioning. Install it using the .NET CLI.

        
            
dotnet add package Microsoft.AspNetCore.Mvc.Versioning
dotnet add package Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer

        
    

3. Configuring API Versioning

Configure API versioning in the Program.cs file.

        
            
var builder = WebApplication.CreateBuilder(args);

// Add services to the container
builder.Services.AddControllers();

// Add API versioning
builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
    options.ApiVersionReader = new UrlSegmentApiVersionReader();
});

// Add versioned API explorer
builder.Services.AddVersionedApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
});

var app = builder.Build();

app.UseHttpsRedirection();

app.MapControllers();
app.Run();

        
    

Configuration Parameters:

• DefaultApiVersion: Specifies the default API version to use when a client does not specify a version.
• AssumeDefaultVersionWhenUnspecified: If set to true, the default API version is assumed when the client does not specify a version.
• ReportApiVersions: Adds the supported API versions to the response headers.
• ApiVersionReader: Determines how the API version is read from the request (e.g., URL segment, query string, header).

4. Versioning by URL Segment

URL segment versioning includes the version in the URL path. This is the most commonly used versioning strategy.

Ensure the ApiVersionReader is set to UrlSegmentApiVersionReader.

        
            
options.ApiVersionReader = new UrlSegmentApiVersionReader();

        
    

Define controllers with versioned routes.

        
            
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/products")]
[ApiController]
public class ProductsV1Controller : ControllerBase
{
    [HttpGet]
    public IActionResult Get() => Ok(new[] { "Product1", "Product2" });
}

[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/products")]
[ApiController]
public class ProductsV2Controller : ControllerBase
{
    [HttpGet]
    public IActionResult Get() => Ok(new[] { "Product1", "Product2", "Product3" });
}

        
    

Explanation:

• ApiVersion: Specifies the version of the API.
• Route: Defines the route for the controller, including the version segment.
• ControllerBase: Base class for MVC controllers without view support.

5. Versioning by Query String

Query string versioning includes the version in the query string of the URL.

Set the ApiVersionReader to QueryStringApiVersionReader.

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

        
    

Define controllers without versioned routes. The version is determined by the query string.

        
            
[ApiVersion("1.0")]
[Route("api/products")]
[ApiController]
public class ProductsV1Controller : ControllerBase
{
    [HttpGet]
    public IActionResult Get() => Ok(new[] { "Product1", "Product2" });
}

[ApiVersion("2.0")]
[Route("api/products")]
[ApiController]
public class ProductsV2Controller : ControllerBase
{
    [HttpGet]
    public IActionResult Get() => Ok(new[] { "Product1", "Product2", "Product3" });
}

        
    

Explanation:

• QueryStringApiVersionReader: Reads the API version from the query string.
• Route: Defines the route for the controller without the version segment.

6. Versioning by HTTP Header

Header versioning includes the version in a custom HTTP header.

Set the ApiVersionReader to HeaderApiVersionReader.

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

        
    

Define controllers without versioned routes. The version is determined by the custom header.

        
            
[ApiVersion("1.0")]
[Route("api/products")]
[ApiController]
public class ProductsV1Controller : ControllerBase
{
    [HttpGet]
    public IActionResult Get() => Ok(new[] { "Product1", "Product2" });
}

[ApiVersion("2.0")]
[Route("api/products")]
[ApiController]
public class ProductsV2Controller : ControllerBase
{
    [HttpGet]
    public IActionResult Get() => Ok(new[] { "Product1", "Product2", "Product3" });
}

        
    

Explanation:

• HeaderApiVersionReader: Reads the API version from a custom HTTP header.
• Route: Defines the route for the controller without the version segment.

7. Combining Versioning Methods

You can combine different versioning methods to provide flexibility to clients.

Set the ApiVersionReader to combine multiple readers.

        
            
options.ApiVersionReader = ApiVersionReader.Combine(
    new UrlSegmentApiVersionReader(),
    new QueryStringApiVersionReader("v"),
    new HeaderApiVersionReader("x-api-version"));

        
    

Define controllers as before, ensuring they can respond to any of the specified versioning methods.

        
            
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/products")]
[ApiController]
public class ProductsV1Controller : ControllerBase
{
    [HttpGet]
    public IActionResult Get() => Ok(new[] { "Product1", "Product2" });
}

[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/products")]
[ApiController]
public class ProductsV2Controller : ControllerBase
{
    [HttpGet]
    public IActionResult Get() => Ok(new[] { "Product1", "Product2", "Product3" });
}

        
    

Explanation:

• ApiVersionReader.Combine: Combines multiple version readers to allow clients to specify the version using different methods.
• Route: Defines the route for the controller, including the version segment.

8. API Versioning Best Practices

• Choose a Consistent Strategy: Choose a versioning strategy that best fits your API and stick with it consistently.
• Deprecate Old Versions: Clearly communicate and provide timelines for deprecating old API versions.
• Document Your API: Ensure that API documentation includes versioning information.
• Test All Versions: Thoroughly test all versions of your API to ensure backward compatibility.
• Use Semantic Versioning: Follow semantic versioning principles to communicate the nature of changes.

9. Comprehensive Example

        
            
var builder = WebApplication.CreateBuilder(args);

// Add services to the container
builder.Services.AddControllers();

// Add API versioning
builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
    options.ApiVersionReader = ApiVersionReader.Combine(
        new UrlSegmentApiVersionReader(),
        new QueryStringApiVersionReader("v"),
        new HeaderApiVersionReader("x-api-version"));
});

// Add versioned API explorer
builder.Services.AddVersionedApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
});

var app = builder.Build();

app.UseHttpsRedirection();

app.MapControllers();
app.Run();

        
    

        
            
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/products")]
[ApiController]
public class ProductsV1Controller : ControllerBase
{
    [HttpGet]
    public IActionResult Get() => Ok(new[] { "Product1", "Product2" });
}

[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/products")]
[ApiController]
public class ProductsV2Controller : ControllerBase
{
    [HttpGet]
    public IActionResult Get() => Ok(new[] { "Product1", "Product2", "Product3" });
}

        
    

Conclusion

API versioning is crucial for maintaining backward compatibility and allowing for incremental improvements. By implementing URL segment, query string, and header versioning, you can provide flexibility to your API clients. Following best practices ensures that your API remains reliable and easy to use. This comprehensive guide provides the tools and knowledge to effectively implement API versioning in your ASP.NET Core 8 Web API projects.