How to implement API versioning using URL, header, and query string in ASP.NET Core?

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 API versioning is and why it matters
How to implement URL versioning in ASP.NET Core
How to implement query string versioning
How to implement header versioning
Real-world use cases and architecture decisions
Advantages and disadvantages of each approach

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:

Some users are still on version 1.0
Others update to version 2.0
Both versions must work without breaking

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:

Prevents breaking changes in production
Supports gradual rollout of new features
Enables A/B testing of APIs
Helps maintain compatibility with multiple client platforms (mobile, web, IoT)

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

DefaultApiVersion: Sets fallback version (v1.0)
AssumeDefaultVersionWhenUnspecified: Prevents errors if version is missing
ReportApiVersions: Adds supported versions in response headers

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:

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

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

Easy to understand and test
SEO-friendly URLs
Works well with API gateways and caching

Disadvantages

URL changes when version changes
Can lead to duplicate routes

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

No need to change route structure
Simple to implement

Disadvantages

Less intuitive for developers
Not ideal for caching mechanisms

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

Keeps URLs clean
Flexible and scalable

Disadvantages

Harder to test manually
Less visible for debugging

Difference Between URL, Query String, and Header Versioning

Feature	URL Versioning	Query String Versioning	Header Versioning
Visibility	High	Medium	Low
Ease of Testing	Easy	Easy	Moderate
Caching Support	Strong	Weak	Moderate
Best Use Case	Public APIs	Legacy systems	Internal 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

API changes break production apps
No backward compatibility
Frequent hotfixes required

After

Stable API lifecycle
Smooth client upgrades
Better developer experience

Advantages of API Versioning

Enables backward compatibility
Supports safe feature evolution
Improves API lifecycle management
Helps in debugging and monitoring

Disadvantages

Increased maintenance effort
Multiple versions to manage
Code duplication in some cases

Best Practices for API Versioning

Use URL versioning for public APIs
Avoid breaking changes in the same version
Deprecate old versions gradually
Maintain clear API documentation

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.