Web API Versioning

What Is API Versioning?

API versioning is the process of iterating different versions of your API.

Why Is API Versioning Required?

While working on an existing application or creating a new one, we may create multiple APIs that may be consumed by many clients. When the business has started to grow and expand, new requirements arise. Due to this, we may need to provide more functionality in the existing APIs. However, existing Web API can be consumed by many clients so how to implement the new feature without impacting the existing consumers? We can solve this problem by versioning our API.

There are some common ways to version a REST API.

1. Versioning through URI

The most commonly used versioning is in which we can add a version to the API base URL.

Example:

http://api-demo.example.com/api/1/employee

This approach is easy to implement and understand, as clients can simply request the desired version of the API by specifying the corresponding URL. Here are the steps to implement URL-based versioning in ASP.NET Core:

Install the Microsoft.AspNetCore.Mvc.Versioning NuGet package in your ASP.NET Core project. You can do this using the Package Manager Console or the NuGet Package Manager in Visual Studio.

In the ConfigureServices method of your Startup.cs file, configure the API versioning options by adding the following code:

  services.AddApiVersioning(options =>

    {

        options.DefaultApiVersion = new ApiVersion(1, 0);

        options.AssumeDefaultVersionWhenUnspecified = true;

        options.ReportApiVersions = true;

        options.ApiVersionReader = new UrlSegmentApiVersionReader();

    });

This code configures the default API version to be 1.0, assumes the default version when not specified in the URL, reports the API versions in the response headers, and uses the URL segment as the versioning source.

In your controller, add the ApiVersion attribute to specify the supported API versions for each action method. For example:

  [ApiController]

  [Route("api/v{version:apiVersion}/[controller]")]

  [ApiVersion("1.0")]

  public class MyController : ControllerBase

  {

      [HttpGet]

      public IActionResult Get()

      {

          return Ok("Version 1.0");

      }

     

      [HttpGet, MapToApiVersion("2.0")]

      public IActionResult GetV2()

      {

          return Ok("Version 2.0");

      }

  }

This code specifies that the controller supports version 1.0 of the API, and that the GetV2 action method supports version 2.0. The [MapToApiVersion] attribute maps the action method to version 2.0.

Test the API by sending requests to the corresponding URLs. For example:

http://localhost:5000/api/v1.0/my -> returns "Version 1.0"

http://localhost:5000/api/v2.0/my -> returns "Version 2.0"

By using URL-based versioning in ASP.NET Core, you can easily manage different versions of your API and provide backward compatibility to existing clients.

2. Query String

Another option for versioning a REST API is to include the version number as a query parameter.

This is a straightforward way to version an API from an implementation point of view.

Example:

https://api-demo.example.com/api/employee/?api-version=2

Follow the same steps and code as mentioned above. change code for AddApiVersioning method. in this only  ApiVersionReader  property is changed.

  services.AddApiVersioning(options =>

    {

        options.DefaultApiVersion = new ApiVersion(1, 0);

        options.AssumeDefaultVersionWhenUnspecified = true;

        options.ReportApiVersions = true;

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

    });

Test the API by sending requests with the "version" query parameter. For example:

http://localhost:5000/api/my?version=1.0 -> returns "Version 1.0"

http://localhost:5000/api/my?version=2.0 -> returns "Version 2.0"

By using query string-based versioning in ASP.NET Core, you can provide a flexible and convenient way for clients to specify the desired version of your API.

3. Custom headers

Define a new header that contains the version number in the request as part of the request header itself.

Example:

GET https://api-demo.example.com/api/employee
Accept-Version: 3

Follow the same steps and code as mentioned above. change code for AddApiVersioning method. in this only  ApiVersionReader  property is changed.

  services.AddApiVersioning(options =>

    {

        options.DefaultApiVersion = new ApiVersion(1, 0);

        options.AssumeDefaultVersionWhenUnspecified = true;

        options.ReportApiVersions = true;

        options.ApiVersionReader = new HeaderApiVersionReader("X-Version");

    });

This code configures the default API version to be 1.0, assumes the default version when not specified in the header, reports the API versions in the response headers, and uses the "X-Version" header as the versioning source.

Test the API by sending requests with the "X-Version" header. For example:

http://localhost:5000/api/my

X-Version: 1.0 -> returns "Version 1.0"

X-Version: 2.0 -> returns "Version 2.0"

By using header-based versioning in ASP.NET Core, you can provide a flexible and non-intrusive way for clients to specify the desired version of your API.

Learn More: https://codelikeadev.com/, https://www.c-sharpcorner.com/, 
                        https://www.dotnettricks.com/, https://blog.devart.com/, 

Continue Reading →