How to Implement API Versioning in ASP.NET Core Web API

Introduction

When you build a Web API in ASP.NET Core, your API will evolve over time. You may add new features, change response formats, or improve existing endpoints. But what happens to existing users who are already using your API?

This is where API versioning becomes very important.

API versioning allows you to maintain multiple versions of your API so that old clients continue to work while new clients can use updated features.

In this article, you will learn how to implement API versioning in ASP.NET Core Web API in a simple, practical, and step-by-step way.

What is API Versioning?

API versioning is a technique that allows different versions of your API to exist at the same time.

In simple words:

Old users continue using version 1
New users can use version 2
Your application remains stable and backward compatible

This is very important in real-world applications where breaking changes can affect thousands of users.

Why API Versioning is Important

API versioning helps you:

Avoid breaking existing clients
Introduce new features safely
Maintain backward compatibility
Manage API lifecycle effectively

Without versioning, even small changes can break applications that depend on your API.

Types of API Versioning in ASP.NET Core

There are multiple ways to implement API versioning:

URL Versioning (most common)
Query String Versioning
Header Versioning
Media Type Versioning

Let’s understand each one in simple terms.

URL Versioning

Version is included in the URL.

Example:

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

This is the easiest and most widely used approach.

Query String Versioning

Version is passed as a query parameter.

Example:

/api/products?version=1

Header Versioning

Version is passed in request headers.

Example:

api-version: 1

Media Type Versioning

Version is specified in the Accept header.

Example:

application/json;v=1

Prerequisites

Before starting, ensure you have:

ASP.NET Core Web API project
.NET SDK installed
Basic understanding of controllers and routing

Step 1: Install API Versioning Package

Run the following command:

dotnet add package Microsoft.AspNetCore.Mvc.Versioning

This package provides built-in support for API versioning.

Step 2: Configure API Versioning in Program.cs

Open your Program.cs file and add the following configuration:

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

Explanation:

AssumeDefaultVersionWhenUnspecified → Uses default version if not provided
DefaultApiVersion → Sets default version
ReportApiVersions → Returns supported versions in response headers

Step 3: Add Versioning to Controller

Now, define API version in your controller.

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

This controller handles version 1 of the API.

Step 4: Create Version 2 of API

Now, let’s create a second version.

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

Now you have two versions running side by side.

Step 5: Using Multiple Versions in Same Controller

You can also support multiple versions in a single controller.

[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("1.0")]
[ApiVersion("2.0")]
public class OrdersController : ControllerBase
{
    [HttpGet]
    [MapToApiVersion("1.0")]
    public IActionResult GetV1()
    {
        return Ok("Orders from Version 1");
    }

    [HttpGet]
    [MapToApiVersion("2.0")]
    public IActionResult GetV2()
    {
        return Ok("Orders from Version 2");
    }
}

This helps reduce code duplication.

Step 6: Configure Query String Versioning

If you want to use query string versioning:

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

Now API can be called like:

/api/products?version=1

Step 7: Configure Header Versioning

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

Request example:

api-version: 1

Step 8: Best Practices for API Versioning

Follow these best practices:

Use clear version naming (v1, v2)
Avoid breaking changes in existing versions
Deprecate old versions gradually
Document all versions properly
Use URL versioning for simplicity

Step 9: Real-World Example

Imagine an e-commerce API:

Version 1:

Returns product name and price

Version 2:

Adds product description and category

Old apps continue using v1, while new apps use v2.

This ensures smooth upgrades without breaking existing users.

Advantages of API Versioning

Better maintainability
Smooth upgrades
Improved developer experience
Backward compatibility

Summary

API versioning in ASP.NET Core Web API is essential for building scalable and future-proof applications. It allows you to introduce changes without breaking existing clients. By using built-in versioning features, you can easily manage multiple API versions using URL, query string, or headers. Following best practices ensures your API remains stable, flexible, and easy to maintain as it evolves.