API versioning is a critical practice in modern application development that allows teams to evolve APIs without breaking existing clients. In enterprise ASP.NET Core applications, APIs are often consumed by mobile apps, third-party systems, frontend frameworks, and microservices. If a breaking change is introduced without versioning, it can cause production outages, client failures, and revenue loss. This guide explains API versioning in ASP.NET Core in a production-grade manner, including definitions, internal behavior, real-world scenarios, implementation strategies, comparison approaches, advantages, trade-offs, and best practices.

What is API Versioning?

API versioning is the strategy of maintaining multiple versions of an API simultaneously so that changes can be introduced without affecting existing consumers.

Real-world analogy:

Think of API versioning like smartphone operating system updates. When a new OS version is released, older apps still continue working because backward compatibility is maintained. Similarly, when you release v2 of your API, clients using v1 should not break immediately.

Without versioning:

With versioning:

Why API Versioning is Important in Production

Consider a fintech ASP.NET Core API that returns transaction data:

Version 1 response:

{
  "id": 1,
  "amount": 5000
}

Later, business requires currency support:

Version 2 response:

{
  "id": 1,
  "amount": 5000,
  "currency": "INR"
}

If currency is added without versioning and frontend validation expects exact schema, it may fail. Versioning ensures structured evolution.

Common API Versioning Strategies

Each approach has different use cases and trade-offs.

Difference Between API Versioning Strategies

StrategyExampleVisibilityEase of TestingREST PurityRecommended For
URL Versioning/api/v1/productsVery ClearEasyModeratePublic APIs
Query String/api/products?api-version=1.0VisibleEasyGoodInternal APIs
Header VersioningHeader: api-version: 1.0HiddenMediumHighEnterprise APIs
Media TypeAccept: application/json;v=1.0HiddenComplexVery HighStrict REST systems

In most real-world ASP.NET Core applications, URL versioning is preferred for clarity and simplicity.

Step 1: Install API Versioning Package

dotnet add package Microsoft.AspNetCore.Mvc.Versioning

Step 2: Configure API Versioning in Program.cs

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddControllers();

var app = builder.Build();

app.MapControllers();

app.Run();

Explanation:

Step 3: Implement URL Versioning in Controller

using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/v{version:apiVersion}/products")]
[ApiVersion("1.0")]
public class ProductsV1Controller : ControllerBase
{
    [HttpGet]
    public IActionResult Get()
    {
        return Ok(new { Message = "Products from Version 1" });
    }
}

[ApiController]
[Route("api/v{version:apiVersion}/products")]
[ApiVersion("2.0")]
public class ProductsV2Controller : ControllerBase
{
    [HttpGet]
    public IActionResult Get()
    {
        return Ok(new { Message = "Products from Version 2 with enhancements" });
    }
}

Now:

Alternative: Query String Versioning

builder.Services.AddApiVersioning(options =>
{
    options.ApiVersionReader = new QueryStringApiVersionReader("api-version");
});

Request example:

/api/products?api-version=2.0

Alternative: Header Versioning

builder.Services.AddApiVersioning(options =>
{
    options.ApiVersionReader = new HeaderApiVersionReader("api-version");
});

Client must send header:

api-version: 2.0

Real Production Scenario

An e-commerce company releases a mobile app integrated with API v1. Later, API v2 introduces discount logic changes. If v1 is removed immediately, older mobile app users experience crashes. By maintaining both versions, users update gradually without service disruption.

This approach prevents breaking changes in distributed systems.

Advantages of API Versioning

Disadvantages and Trade-offs

Common Mistakes Developers Make

Best Practices for Enterprise Applications

When to Introduce a New API Version

Create a new version when:

Avoid new version when:

Summary

Implementing API versioning in ASP.NET Core enables safe and controlled evolution of APIs without breaking existing clients. By configuring API versioning services, selecting an appropriate strategy such as URL, query string, or header versioning, and maintaining multiple controller versions, organizations can introduce new features while preserving backward compatibility. Although versioning increases maintenance complexity, it is essential for enterprise-grade systems where APIs are consumed by multiple external clients. A disciplined versioning and deprecation strategy ensures long-term stability, scalability, and seamless user experience in modern distributed applications.