URL and Header-based Versioning - (ASP.NET Core API Versioning)

When it comes to versioning our APIs, we need to decide the approach we are going to take. In this article, we will explore URL and Header-based approach of versioning in ASP.NET Core API versioning.

Syntax

To use URL-based API versioning, you need to add the following code to your Startup.cs file:

services.AddApiVersioning(options =>
{
    options.ApiVersionReader = new UrlSegmentApiVersionReader();
});

To use Header-based API versioning, you need to add the following code to your Startup.cs file:

services.AddApiVersioning(options =>
{
    options.ApiVersionReader = new HeaderApiVersionReader("X-API-Version");
});

Example

Here is an example of URL-based API versioning for the BooksController:

[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("1.0")]
public class BooksController : ControllerBase
{
    [HttpGet("{id}")]
    public IActionResult Get(int id)
    {
        var book = new { Id = id, Title = "Book 1", Author = "Author 1" };
        return Ok(book);
    }
}

Here is an example of Header-based API versioning for the BooksController:

[ApiController]
[Route("[controller]")]
public class BooksController : ControllerBase
{
    [HttpGet("{id}")]
    [MapToApiVersion("1.0")]
    public IActionResult Get(int id)
    {
        var book = new { Id = id, Title = "Book 1", Author = "Author 1" };
        return Ok(book);
    }
}

Output

The output will be based on the versioning approach you choose. For URL-based versioning, you will have to specify the API version in the URL. For Header-based versioning, you will have to specify the API version in the header.

Explanation

API versioning is important when building APIs. It allows you to make changes to your API without breaking your clients. There are many ways to version an API, and two of them are URL-based versioning and Header-based versioning.

URL-based versioning involves specifying the API version in the URL. This means that clients will have to modify the URL every time there is a new API version.

Header-based versioning involves specifying the API version in a header. This means that the clients will not have to modify the URL. They can simply send the API version in the request header.

Use

URL-based and Header-based versioning have their own advantages and disadvantages. It is up to you to choose the one that best fits your requirements.

URL-based versioning is easy to implement and understand. It is also easy to test and debug.

Header-based versioning is more flexible than URL-based versioning. It allows you to add multiple API versions without modifying the URL.

Important Points

• API versioning is important to avoid breaking changes for clients.
• URL-based versioning involves specifying the API version in the URL.
• Header-based versioning involves specifying the API version in a header.

Summary

In this article, we discussed URL-based and Header-based versioning in ASP.NET Core API versioning. We explained their syntax, example, output, explanation, use, and important points. API versioning is important, and you need to choose a versioning approach that best fits your requirements.