API Versioning in ASP.NET Core: Strategies for Building Backward-Compatible APIs

APIs evolve over time. New features are added, response models change, endpoints are deprecated, and business requirements shift. Without a clear versioning strategy, even small API changes can break existing clients and create costly compatibility issues.

ASP.NET Core supports API versioning through multiple strategies, allowing you to introduce new functionality while maintaining backward compatibility for existing consumers. Choosing the right versioning approach helps reduce breaking changes, simplifies client upgrades, and enables long-term API maintenance.

Rather than treating versioning as an afterthought, this article explains the most common API versioning strategies, how to implement them in ASP.NET Core, and when each approach is appropriate.

Note: API versioning is not only about supporting multiple versions simultaneously. It's also about providing a predictable upgrade path for API consumers.

Why API Versioning Matters

Without versioning, introducing changes can result in:

• Broken client applications

• Failed mobile app updates

• Integration failures

• Increased maintenance costs

• Difficult deployments

• Poor developer experience

A well-defined versioning strategy allows APIs to evolve without disrupting existing integrations.

Common Versioning Strategies

ASP.NET Core supports several versioning approaches.

Each strategy has advantages depending on the API's consumers and deployment model.

URL Versioning

URL versioning is the most common and easiest approach to understand.

Example endpoint:

GET /api/v1/products

GET /api/v2/products

Clients explicitly specify which version they want to consume, making debugging and documentation straightforward.

Installing API Versioning

Install the required NuGet package.

dotnet add package Asp.Versioning.Mvc

This package adds API versioning support to ASP.NET Core applications.

Configuring API Versioning

Register API versioning during application startup.

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion =
        new ApiVersion(1, 0);

    options.AssumeDefaultVersionWhenUnspecified = true;

    options.ReportApiVersions = true;
});

This configuration automatically assumes version 1.0 when a client doesn't specify an API version.

Creating a Versioned Controller

Decorate controllers using the ApiVersion attribute.

[ApiController]
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/products")]
public class ProductsController : ControllerBase
{
    [HttpGet]
    public IActionResult Get()
    {
        return Ok();
    }
}

Requests targeting /api/v1/products are automatically routed to this controller.

Supporting Multiple Versions

A controller can support multiple API versions.

[ApiVersion("1.0")]
[ApiVersion("2.0")]
public class ProductsController : ControllerBase
{
}

This approach is useful when most functionality remains unchanged across versions.

Creating a New API Version

As APIs evolve, newer versions can expose additional functionality.

[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/products")]
public class ProductsV2Controller : ControllerBase
{
    [HttpGet]
    public IActionResult Get()
    {
        return Ok(new
        {
            Version = "2.0",
            SupportsDiscounts = true
        });
    }
}

Creating separate controllers often improves maintainability when versions diverge significantly.

API Version Lifecycle

flowchart LR

A[Version 1]
B[Version 2]
C[Version 3]
D[Deprecation]
E[Retirement]

A --> B
B --> C
C --> D
D --> E

Versioning allows new functionality to be introduced while giving clients time to migrate.

Deprecating an API Version