Introduction

In modern backend development, especially in ASP.NET Core Web API projects, API versioning is not optional—it is a foundational design decision. As your application evolves, you will inevitably change response formats, add fields, deprecate endpoints, or improve performance. Without versioning, even a small change can break mobile apps, frontend clients, or third-party integrations already consuming your API.

For example, imagine an e-commerce app where version 1 of the API returns only product name and price. Later, you add discount and stock fields in version 2. If you change the existing API directly, older mobile apps may crash because they are not expecting new fields or structure.

This is where API versioning in ASP.NET Core becomes critical for backward compatibility, scalability, and safe feature rollout.

In this article, you will learn in detail:

What is API Versioning?

API versioning is the practice of maintaining multiple versions of an API simultaneously so that existing clients continue to work even after updates are made.

Real-Life Analogy

Think of API versioning like Android app updates:

Similarly, your backend API must support both old and new clients.

Why API Versioning is Important in Real Projects

In real-world enterprise systems and cloud-based applications, API versioning solves multiple critical problems:

Real-World Scenario

A fintech application releases a new transaction API with enhanced security. Older mobile apps still rely on the previous structure. Without versioning, all users would be forced to update the app immediately—which is not practical.

Step 1: Install Required Package

To enable API versioning in ASP.NET Core, install the official package:

dotnet add package Microsoft.AspNetCore.Mvc.Versioning

This package provides built-in support for handling different API versions efficiently.

Step 2: Configure API Versioning in ASP.NET Core

Update Program.cs with detailed configuration:

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

Explanation

Example Response Header

api-supported-versions: 1.0, 2.0

URL Versioning in ASP.NET Core

What is URL Versioning?

In this approach, the API version is part of the URL path.

Example:

Implementation

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

Version 2:

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

Real-World Use Case

Public APIs (like payment gateways or e-commerce APIs) commonly use URL versioning because it is explicit and easy to debug.

Advantages

Disadvantages

Query String Versioning in ASP.NET Core

What is Query String Versioning?

Version is passed as a query parameter in the URL.

Example:

/api/products?api-version=1.0

Configuration

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

Real-World Use Case

Used in systems where modifying URL paths is difficult (e.g., legacy systems or shared endpoints).

Advantages

Disadvantages

Header Versioning in ASP.NET Core

What is Header Versioning?

Version is passed through HTTP headers instead of URL.

Example:

X-Version: 1.0

Configuration

options.ApiVersionReader = new HeaderApiVersionReader("X-Version");

Real-World Use Case

Used in enterprise internal APIs or microservices where clean URLs are required.

Advantages

Disadvantages

Difference Between URL, Query String, and Header Versioning

FeatureURL VersioningQuery String VersioningHeader Versioning
VisibilityHighMediumLow
Ease of TestingEasyEasyModerate
Caching SupportStrongWeakModerate
Best Use CasePublic APIsLegacy systemsInternal APIs

Combining Multiple Versioning Strategies

In real-world ASP.NET Core applications, you can combine multiple strategies:

options.ApiVersionReader = ApiVersionReader.Combine(
    new QueryStringApiVersionReader("api-version"),
    new HeaderApiVersionReader("X-Version")
);

This ensures flexibility for different types of clients.

Before vs After Versioning (Real Scenario)

Before

After

Advantages of API Versioning

Disadvantages

Best Practices for API Versioning

Summary

API versioning in ASP.NET Core is a critical practice for building scalable, maintainable, and production-ready APIs. By implementing URL versioning, query string versioning, and header versioning, developers can ensure backward compatibility while continuously evolving their applications. Each approach serves different use cases—URL versioning is best for public APIs, query string works well in legacy systems, and header versioning fits internal architectures. Choosing the right strategy, or combining them, helps organizations deliver updates safely without disrupting existing users.