API Versioning in ASP.NET Core Minimal API

Back to: ASP.NET Core Web API Tutorials

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

In this article, I will discuss How to Implement API Versioning in ASP.NET Core Minimal API with examples. Please read our previous articles discussing How to Implement JWT Authentication in ASP.NET Core Minimal API with Examples. We will be working with the same project as we worked so far with ASP.NET Core Minimal API.

What is API Versioning?

API Versioning is a feature for managing changes and backward compatibility in web services. As the business grows and the number of clients of our application increases, we may need to change our Web Services. Versioning allows developers to modify or improve their services without breaking the functionality of existing clients.

API Versioning enables multiple versions of an API to exist in the application. As a result, developers can introduce new features, fix bugs, or make other changes to enhance the application while still supporting older versions of the API. This ensures backward compatibility and helps maintain a stable and predictable API for clients.

So, we need to keep the existing services as they are so that the existing client applications will not break. They worked as they were, and we need to develop a new version of the Web API service that will start being consumed by the new client applications. Later, the existing clients will migrate to the new version of the API.

Why API Versioning?

API Versioning is important for several reasons. They are as follows:

• Backward Compatibility: Allows existing clients to continue functioning as expected without being affected by changes or updates to the API or when the new versions of the API are released.
• Smooth Transitions: Allows existing clients to upgrade to newer versions of the API at their own pace rather than forcing them to update immediately.
• Feature Deprecation: This provides a way to deprecate and eventually remove outdated functionality in a controlled manner.
• Client Expectations: Helps manage client expectations by clearly defining which version of the API they are interacting with, thus reducing confusion and potential errors.

Different Versioning Techniques in ASP.NET Core Minimal API

Similar to ASP.NET Core Web API, in ASP.NET Core Minimal API, versioning techniques can also be implemented to manage and control API versions in 4 ways. They are as follows:

• URI Versioning: The version is part of the URL path.
• Query String Versioning: The version is specified in the query string parameter.
• Header Versioning: The version information is passed in a custom HTTP header.
• Media Type Versioning (Content Negotiation): The version is specified in the Accept header as part of the media type.

URL Path Versioning in ASP.NET Core Minimal API

In URL path versioning, the version number is included in the URL path. For example, https://api.example.com/v1/employees. Let us understand this with an example. Please modify the Program class as follows:

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

app.MapGet("/v1/employees", () => "Version 1 - Get all employees");
app.MapGet("/v2/employees", () => "Version 2 - Get all employees");

app.Run();

Here,

• Pros: Explicit versioning in URLs makes it easy for clients to understand and use different versions.
• Cons: It can have more URLs and make routing complex as the number of versions increases.

Query String Versioning in ASP.NET Core Minimal API

In query string versioning, the version number is included as a query parameter. For example, https://api.example.com/employees?api-version=1. Let us understand this with an example. Please modify the Program class as follows:

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

app.MapGet("/employees", (HttpContext context) =>
{
    var version = context.Request.Query["api-version"];
    if (version == "1")
    {
        return "Version 1 - Get all employees";
    }
    else if (version == "2")
    {
        return "Version 2 - Get all employees";
    }
    return "Unknown version";
});

app.Run();

Here,

• Pros: Keeps URLs clean and allows clients to specify the version dynamically.
• Cons: Requires clients to actively manage and specify the version, which might be error-prone.

Header Versioning in ASP.NET Core Minimal API

In header versioning, the version number is included in the request headers. For example:
GET https://api.example.com/employees
Headers: api-version: 1
Let us understand this with an example. Please modify the Program class as follows:

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

app.MapGet("/employees", (HttpContext context) =>
{
    var version = context.Request.Headers["api-version"].ToString();
    if (version == "1")
    {
        return "Version 1 - Get all employees";
    }
    else if (version == "2")
    {
        return "Version 2 - Get all employees";
    }
    return "Unknown version";
});

app.Run();

Here,

• Pros: Provides a clean separation of concerns, with versioning handled in the HTTP headers.
• Cons: Requires clients to correctly set and manage headers, which can be challenging for some implementations.

Media Type Versioning in ASP.NET Core Minimal API

In media type versioning, the version number is included in the Accept header as a part of the media type. For example:
GET https://api.example.com/employees
Headers: Accept: application/vnd.example.v1+json
Let us understand this with an example. Please modify the Program class as follows:

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

app.MapGet("/employees", (HttpContext context) =>
{
    var acceptHeader = context.Request.Headers["Accept"].ToString();
    if (acceptHeader.Contains("application/vnd.example.v1+json"))
    {
        return "Version 1 - Get all employees";
    }
    else if (acceptHeader.Contains("application/vnd.example.v2+json"))
    {
        return "Version 2 - Get all employees";
    }
    return "Unknown version";
});

app.Run();

Here,

• Pros: Like header versioning, allows clear separation of concerns and handles versioning through media types.
• Cons: Similar challenges as header versioning in terms of client implementation and management.

Choosing the Right Versioning Strategy

The choice of versioning strategy depends on factors such as API complexity, client needs, and preferences. Consider the following guidelines:

• URL-based versioning is straightforward and explicit but can have more endpoint URLs.
• Query parameter versioning keeps URLs clean but requires clients to manage versioning actively.
• Header and media type versioning offer cleaner separation but require clients to set headers, which can be challenging.

So, API Versioning is important for maintaining backward compatibility and ensuring a smooth evolution of APIs. ASP.NET Core provides several techniques for versioning APIs, allowing developers to choose the one that best fits their needs. Each method has its pros and cons, and the choice of versioning strategy depends on factors like client flexibility, ease of use, and adherence to RESTful principles.

In the next article, I will discuss How to Implement Microservices using ASP.NET Core Web API with an Example. In this article, I explain How to Implement API Versioning in ASP.NET Core Minimal API with Examples. I hope you enjoy this article, API Versioning in ASP.NET Core Minimal API.