Asp.Net Web Api Query String And Header Versioning Complete Guide

 Last Update:2025-06-23T00:00:00     .NET School AI Teacher - SELECT ANY TEXT TO EXPLANATION.    7 mins read      Difficulty-Level: beginner

Understanding the Core Concepts of ASP.NET Web API Query String and Header Versioning

ASP.NET Web API Query String and Header Versioning

1. Query String Versioning

Overview:

  • Implementation: This approach involves appending a version number to the URL as a query parameter.
  • Example:
    • GET /api/products?api-version=1.0
    • GET /api/products?api-version=2.0

Advantages:

  • Simplicity: Easy to implement and understand.
  • Client Control: Developers can specify the version they want to use, providing flexibility.
  • Client Compatibility: Well-suited for clients where the application handling logic can easily append the query string (e.g., web browsers, JavaScript clients).

Disadvantages:

  • Statelessness Compromise: Each request must include the version information, leading to repetitive query strings.
  • Discoverability: Harder to maintain documentation, as each API endpoint might need multiple examples.

Configuration Steps:

  1. Install NuGet Package:

    Install-Package Microsoft.AspNetCore.Mvc.Versioning

  2. Configure Versioning in Startup:

    public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    services.AddApiVersioning(options =>
    {
        options.ApiVersionReader = new QueryStringApiVersionReader();
        options.DefaultApiVersion = new ApiVersion(1, 0);
        options.AssumeDefaultVersionWhenUnspecified = true;
    });
}

  3. Decorate Controllers and Actions:

    [ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/[controller]")]
public class ProductsControllerV1 : ControllerBase
{
    // Controller implementation for version 1
}

[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/[controller]")]
public class ProductsControllerV2 : ControllerBase
{
    // Controller implementation for version 2
}

  4. Testing: Use tools like Postman to test different versions:

    • GET /api/products?api-version=1.0
    • GET /api/products?api-version=2.0

2. Header Versioning

Overview:

  • Implementation: This approach uses a custom HTTP header to specify the API version.
  • Example:
    • GET /api/products with header x-api-version: 1.0
    • GET /api/products with header x-api-version: 2.0

Advantages:

  • Security: Allows seamless transitions without exposing version information in the URL.
  • Uniformity: Consistent with RESTful principles; versioning is dictated by headers, maintaining URL simplicity.
  • Better Caching: URLs remain constant, aiding with caching strategies.

Disadvantages:

  • Complexity: Requires clients to manage additional headers, increasing implementation overhead.
  • Configuration: More complex to set up and manage multiple versions in the backend.

Configuration Steps:

  1. Install NuGet Package:

    Install-Package Microsoft.AspNetCore.Mvc.Versioning

  2. Configure Versioning in Startup:

    public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    services.AddApiVersioning(options =>
    {
        options.HeaderParameter = "x-api-version";
        options.DefaultApiVersion = new ApiVersion(1, 0);
        options.AssumeDefaultVersionWhenUnspecified = true;
    });
}

  3. Decorate Controllers and Actions:

    [ApiVersion("1.0")]
[Route("api/[controller]")]
public class ProductsControllerV1 : ControllerBase
{
    // Controller implementation for version 1
}

[ApiVersion("2.0")]
[Route("api/[controller]")]
public class ProductsControllerV2 : ControllerBase
{
    // Controller implementation for version 2
}

  4. Testing: Use tools like Postman to test different versions:

    • GET /api/products with header x-api-version: 1.0
    • GET /api/products with header x-api-version: 2.0

Conclusion

Online Code run

🔔 Note: Select your programming language to check or run code at

💻 Run Code Compiler

Step-by-Step Guide: How to Implement ASP.NET Web API Query String and Header Versioning

Example 1: Query String Versioning

Step 1: Create a New ASP.NET Web API Project

  1. Open Visual Studio.
  2. Click on Create a new project.
  3. Select ASP.NET Core Web Application.
  4. Click on Next.
  5. Enter your project name (e.g., "QueryStringVersioningDemo") and click Create.
  6. Choose the application template API and click Create.

Step 2: Add Dependencies

In this example, we don't need any external dependencies because built-in capabilities are sufficient.

Step 3: Implement Query String Versioning in the Startup Class

Open Program.cs (for .NET 6 and above) or Startup.cs and add the following code:

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

public class Program
{
    public static void Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);

        // Add services to the container.
        builder.Services.AddControllers()
            .AddApiVersioning(o => 
                {
                    o.ApiVersionReader = ApiVersionReader.QueryStringApiVersionReader();
                    o.DefaultApiVersion = new ApiVersion(1, 0);
                    o.AssumeDefaultVersionWhenUnspecified = true;
                });

        builder.Services.AddEndpointsApiExplorer();
        builder.Services.AddSwaggerGen();

        var app = builder.Build();

        // Configure the HTTP request pipeline.
        if (app.Environment.IsDevelopment())
        {
            app.UseSwagger();
            app.UseSwaggerUI();
        }

        app.UseHttpsRedirection();

        app.UseAuthorization();

        app.MapControllers();

        app.Run();
    }
}

Step 4: Create Versions of Your Controller

Create two controllers, each representing a different version:

  1. V1 Controller:

    using Microsoft.AspNetCore.Mvc;

[ApiController]
[ApiVersion("1.0")]
[Route("api/[controller]")]
public class TestController : ControllerBase
{
    [HttpGet(Name = "GetTestV1")]
    public IActionResult Get()
    {
        return Ok($"Hello from V1 of TestController");
    }
}

  2. V2 Controller:

    using Microsoft.AspNetCore.Mvc;

[ApiController]
[ApiVersion("2.0")]
[Route("api/[controller]")]
public class TestController : ControllerBase
{
    [HttpGet(Name = "GetTestV2")]
    public IActionResult Get()
    {
        return Ok($"Hello from V2 of TestController");
    }
}

Step 5: Testing the Versioning

Run your application and test the endpoints:

  • For V1: https://localhost:<port>/api/test?api-version=1.0
  • For V2: https://localhost:<port>/api/test?api-version=2.0

Without specifying the api-version, it should default to V1, e.g.,:

  • Default (Assuming V1): https://localhost:<port>/api/test

Example 2: Header Versioning

Step 1: Create a New ASP.NET Web API Project

Follow the same steps as described in Example 1 to create a new ASP.NET Web API project.

Step 2: Implement Header Versioning in the Startup Class

Modify Program.cs or Startup.cs to configure header-based versioning:

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddControllers()
    .AddApiVersioning(o =>
    {
        o.ApiVersionReader = ApiVersionReader.HeaderApiVersionReader("api-version");
        o.DefaultApiVersion = new ApiVersion(1, 0);
        o.AssumeDefaultVersionWhenUnspecified = true;
    });

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();
app.Run();

Step 3: Create Versions of Your Controller

Again, you'll need two versions of the TestController.

  1. V1 Controller:

    using Microsoft.AspNetCore.Mvc;

[ApiController]
[ApiVersion("1.0")]
[Route("api/[controller]")]
public class TestController : ControllerBase
{
    [HttpGet(Name = "GetTestV1")]
    public IActionResult Get()
    {
        return Ok($"Hello from V1 of TestController");
    }
}

  2. V2 Controller:

    using Microsoft.AspNetCore.Mvc;

[ApiController]
[ApiVersion("2.0")]
[Route("api/[controller]")]
public class TestController : ControllerBase
{
    [HttpGet(Name = "GetTestV2")]
    public IActionResult Get()
    {
        return Ok($"Hello from V2 of TestController");
    }
}

Step 4: Testing the Versioning

Run your application and test the endpoints by setting the api-version header in the request.

Using Postman or curl, set up the requests like this:

  • For V1:

    GET https://localhost:<port>/api/test
Headers:
api-version: 1.0

  • For V2:

    GET https://localhost:<port>/api/test
Headers:
api-version: 2.0

Without specifying the api-version header, it should default to V1:

  • Default (Assuming V1): 
    GET https://localhost:<port>/api/test

Summary

In these steps, you learned how to implement both query string and header versioning in ASP.NET Core Web API.

  • Query String Versioning: Clients specify the API version in the query string of the URL, such as ?api-version=1.0.
  • Header Versioning: Clients specify the API version in an HTTP request header, such as api-version: 1.0.

Top 10 Interview Questions & Answers on ASP.NET Web API Query String and Header Versioning

1. What is ASP.NET Web API versioning?

Answer: ASP.NET Web API versioning allows developers to manage changes in an API over time, ensuring backward compatibility. This is crucial as new features and updates are introduced, without breaking existing client applications.

2. What are the common methods of versioning in ASP.NET Web API?

Answer: Common methods of versioning in ASP.NET Web API include URI-based versioning (using routes or query strings), header-based versioning, and media-type-based versioning (using the Accept or Content-Type headers).

3. How do you implement Query String Versioning in ASP.NET Web API?

Answer: To implement Query String Versioning, you can extend the System.Web.Http.Controllers.IHttpControllerSelector. Override the SelectController method to check the request.GetQueryNameValuePairs() for a version parameter and map it to the appropriate controller.

Example:

public class VersionedControllerSelector : IHttpControllerSelector {
    private readonly IHttpControllerSelector _defaultControllerSelector;

    public VersionedControllerSelector(HttpConfiguration config) {
        _defaultControllerSelector = config.Services.GetHttpControllerSelector();
    }

    public IDictionary<string, HttpControllerDescriptor> GetControllerMapping() {
        return _defaultControllerSelector.GetControllerMapping();
    }

    public HttpControllerDescriptor SelectController(HttpRequestMessage request) {
        var controllers = GetControllerMapping();
        var routeData = request.GetRouteData();
        var controllerName = (string)routeData.Values["controller"];
        var version = request.GetQueryNameValuePairs().FirstOrDefault(q => q.Key == "version").Value;

        if (!string.IsNullOrEmpty(version)) {
            controllerName = $"{controllerName}v{version}";
        }

        return controllers.TryGetValue(controllerName, out var controllerDescriptor) ? controllerDescriptor : null;
    }
}

4. Can you provide an example of Header Versioning in ASP.NET Web API?

Answer: Yes, Header Versioning involves sending the API version in a custom HTTP header, often named api-version.

Example:

using System.Web.Http.Controllers;
using System.Web.Http.Routing;

public class VersionedControllerSelector : IHttpControllerSelector {
    private readonly IHttpControllerSelector _defaultControllerSelector;

    public VersionedControllerSelector(HttpConfiguration config) {
        _defaultControllerSelector = config.Services.GetHttpControllerSelector();
    }

    public IDictionary<string, HttpControllerDescriptor> GetControllerMapping() {
        return _defaultControllerSelector.GetControllerMapping();
    }

    public HttpControllerDescriptor SelectController(HttpRequestMessage request) {
        var controllers = GetControllerMapping();
        var routeData = request.GetRouteData();
        var controllerName = (string)routeData.Values["controller"];
        var versionHeader = request.Headers.GetValues("api-version").FirstOrDefault();

        if (!string.IsNullOrEmpty(versionHeader)) {
            controllerName = $"{controllerName}v{versionHeader}";
        }

        return controllers.TryGetValue(controllerName, out var controllerDescriptor) ? controllerDescriptor : null;
    }
}

5. What are the advantages of using Query String Versioning?

Answer: Query String Versioning is easy to implement because it does not require any special handling of HTTP headers. It is straightforward for clients to send version information as part of the request URL. However, it can make URLs harder to read and can be less secure because version information appears in URLs.

6. What are the advantages of using Header Versioning?

Answer: Header Versioning enhances security because version information is not exposed in URLs, which could be logged or cached by intermediaries. It is cleaner and more flexible, as version information is isolated from the request path and query strings. However, it requires clients to be updated to include version information in the api-version header.

7. Can Query String Versioning lead to caching issues?

Answer: Yes, since version information is included in the URL, different client requests for the same resource but different versions could be cached, potentially leading to incorrect data being served.

8. How do you configure a Web API to support multiple versioning strategies?

Answer: You can configure ASP.NET Web API to support multiple versioning strategies by creating custom implementations of IHttpControllerSelector for different versioning mechanisms. Apply the appropriate selector based on the request characteristics or defaults.

9. What is the recommended best practice for ASP.NET Web API versioning in large-scale applications?

Answer: Best practices for large-scale applications recommend using Header Versioning due to its security and flexibility benefits. Additionally, consider gradual deprecation of older versions, strong documentation, and clear communication with clients regarding version changes.

10. How can you handle breaking changes in a versioned ASP.NET Web API?

Answer: To handle breaking changes, follow a rolling upgrade strategy by introducing new versions of your API without removing existing ones. Clearly document the differences between versions and provide migration guides or tools to help clients transition to newer versions.

You May Like This Related .NET Topic

📥 Download Code ▶️ Watch Online 📖 Read Description

Login to post a comment.