API Versioning in ASP.NET Core

Introduction

API Versioning is very important and it should be implemented in every API application. In this artilcle, we will use different availeble options for versioning in ASP.NET Core API Application. Let's see how to achieve this in ASP.NET Core.

Used tools and packages

• Visual Studio 2017 community edition
• .NET Core 2.1
• Versioning package: Microsoft.AspNetCore.Mvc.Versioning 3.0.0

We can understand versioning in following steps

1. Create an API App Using a .NET Core 2.0 Template in VS 2017
2. Install the NuGet Package for API Versioning
3. Modify Startup Class
4. Create Multiple Versions of the Sample API
5. Use different ways by which you can specify the version of the API
6. Other Useful Features

Create an API App Using a .NET Core 2.0 Template in VS 2017

Open your Visual Studio 2017 -> Create New Project -> Select Core Web application:

Visual Studio will create a api application with default template for you.

Install the NuGet Package for API Versioning

The first step is to install the NuGet package for API Versioning. Open NuGet package manager and search with "Microsoft.AspNetCore.Mvc.Versioning", select package version 3.0.0 and click on Install

Modify Startup Class

After the NuGet package is installed, add the API Versioning service in the ConfigureService method as shown below:

services.AddApiVersioning(v =>
{
  v.ReportApiVersions = true;
  v.AssumeDefaultVersionWhenUnspecified = true;
  v.DefaultApiVersion = new ApiVersion(1, 0);
  //v.ApiVersionReader = new HeaderApiVersionReader("x-api-version"); //HTTP Header-Based Versioning
});

Some details here:

• ReportApiVersions: used to add the API versions in the response header see below:
  
• AssumeDefaultVersionWhenUnspecified: used to set the default version when the client request has not specified any versions. Without this flag, the UnsupportedApiVersion exception will occur when the version is not specified by the request endpoint.
• DefaultApiVersion: used to set the default version count.

Create Multiple Versions of the Sample API

Now you can create multiple versions of our Values API.
For now, just keep the GET method and remove the rest of the methods and create version 1.0 and 2.0 of the same API, as shown below:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;

namespace APIVersioning.Controllers
{
    [ApiVersion("1.0")]
    [Route("api/v{v:apiVersion}/Values")] //URL-Based Versioning
    //[Route("api/Values")] //Query String-Based Versioning
    [ApiController]
    public class ValuesV1Controller : ControllerBase
    {
        // GET api/values
        [HttpGet]
        public ActionResult<IEnumerable<string>> Get()
        {
            return new string[] { "value1 Version 1.0", "value2" };
        }
    }

    [ApiVersion("2.0")]
    [Route("api/v{v:apiVersion}/Values")] //URL-Based Versioning
    //[Route("api/Values")] //Query String-Based Versioning
    [ApiController]
    public class ValuesV2Controller : ControllerBase
    {
        // GET api/values
        [HttpGet]
        public ActionResult<IEnumerable<string>> Get()
        {
            return new string[] { "value1 Version 2.0", "value2" };
        }
    }
}

Use different ways by which you can specify the version of the API

• Query String-Based Versioning:
  Uncomment attribute [Route("api/Values")] at the action.
  In this, you can specify the version of the API in the query string. For example, to call version 2.0 of the Values API, the below call should work:
  

  /api/values?api-version=1.0
  /api/values?api-version=2.0​

  

• URL-Based Versioning
  Uncomment attribute [Route("api/v{v:apiVersion}/Values")] at action
  The below call will return the version 1.0 and 2.0 of the API:
  

  /api/v1.0/values 
  /api/v2.0/values​

  

  This approach is more readable and better to use.
• HTTP Header-Based Versioning
  Uncomment following line in startup class:
  

  //v.ApiVersionReader = new HeaderApiVersionReader("x-api-version"); //HTTP Header-Based Versioning​

  Once the API Version reader is enabled, you can specify the API version while calling this particular API.
  

Other Useful Features

• Deprecating the Versions
  Sometimes we need to deprecate some of the versions of the API, but we do not wish to completely remove that particular version of the API.
  In such cases, we can set the Deprecated flag to true for that API, as shown below:
  

  [ApiVersion("1.0", Deprecated = true)]
  [Route("api/v{v:apiVersion}/Values")] //URL-Based Versioning
  public class ValuesV1Controller: Controller 
  {
    //// Code
  }​

• API Version Neutral
  There might be a case when we need to remove the version for some specific APIs. In such cases, we can remove version of this API by adding the attribute [ApiVersionNeutral] as shown below:
  

  [ApiVersionNeutral] 
  [Route("api/Values")] //URL-Based Versioning
  public class ValuesV1Controller: Controller 
  {
    //// Code
  }​

Conclusion

Hopes this article will be helpful to implement versioning in API ASP.Net Core Application.