Your ASP.NET Core Web API will change over time as you develop it. You can enhance current endpoints, modify answer formats, or add new functionalities. However, what happens to current users who have already made use of your API? API versioning becomes crucial in this situation.

By maintaining different versions of your API, you can enable new clients to utilize current features while maintaining the functionality of older clients. This post will teach you a straightforward, useful, and methodical approach to implementing API versioning in ASP.NET Core Web API.

What is versioning of an API?
One method that enables many versions of your API to exist simultaneously is called API versioning.

To put it simply:

  • Version 1 is still being used by older users.
  • Version 2 is available to new users.
  • Your program is still reliable and compatible with older versions.

In real-world systems, where disruptive changes can impact thousands of users, this is crucial.

Why API Versioning is Important
API versioning helps you:

  1. Avoid breaking existing clients
  2. Introduce new features safely
  3. Maintain backward compatibility
  4. 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:

  1. AssumeDefaultVersionWhenUnspecified → Uses default version if not provided
  2. DefaultApiVersion → Sets default version
  3. 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
Building scalable and future-proof apps requires the use of ASP.NET Core Web API versioning. It enables you to implement changes without upsetting current customers. You may simply manage different API versions using URL, query string, or headers by utilizing built-in versioning functionality. As your API develops, adhering to best practices guarantees that it will continue to be dependable, adaptable, and simple to maintain.