How to implement Versioning in Web API?

Implementing API Versioning in ASP.NET Core Web API is important to maintain backward compatibility when your API evolves.

For example:

v1 → Old clients still work
v2 → New features added

✅ Why API Versioning?

Suppose you release:

Version 1

GET /api/products

Later you change response structure → this breaks old clients.

So you create:

GET /api/v2/products

Now:

Old apps use v1
New apps use v2

✅ Step 1: Install API Versioning Package

Install NuGet package:

Microsoft.AspNetCore.Mvc.Versioning

Package: Microsoft.AspNetCore.Mvc.Versioning

✅ Step 2: Configure Versioning in Program.cs

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

What this does

Option	Purpose
AssumeDefaultVersionWhenUnspecified	Uses default version
DefaultApiVersion	Default version (v1)
ReportApiVersions	Adds supported versions in header

✅ Method 1: URL Versioning (Most Common)

api/v1/products
api/v2/products

Controller Version 1

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

Controller Version 2

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

✅ Method 2: Query String Versioning

api/products?version=1.0
api/products?version=2.0

Enable:

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

✅ Method 3: Header Versioning (Professional APIs)

GET /api/products
Header:
api-version: 1.0

Enable:

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

✅ Method 4: Media Type Versioning (Advanced)

Header:

Accept: application/json;version=1.0

Enable:

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

🏆 Interview Best Answer

If interviewer asks:

How do you implement API versioning?

You can answer:

"I use Microsoft.AspNetCore.Mvc.Versioning package in ASP.NET Core.
I configure versioning in Program.cs and use ApiVersion attribute in controllers.
I usually implement URL versioning like api/v1/products and api/v2/products."

✅ Best Practice (Real-World)

Most companies use:

⭐ URL Versioning
OR
⭐ Header Versioning

Recommended:

api/v1/products
api/v2/products

Bonus: Same Controller Multiple Versions

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

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

Summary

Version Type	Example	Recommended
URL	/api/v1/products	⭐ Best
Query	?version=1	Good
Header	api-version	Professional
Media Type	Accept header	Advanced