Click here to Skip to main content
15,038,237 members
Articles / Web Development / ASP.NET / ASP.NET Core
Technical Blog
Posted 1 Sep 2017

Tagged as

Stats

14.4K views
5 bookmarked

Versioning ASP.NET Core 2.0 Web API

Rate me:
Please Sign up or sign in to vote.
5.00/5 (4 votes)
1 Sep 2017CPOL2 min read
How to implement versioning in ASP.NET Core Web API. Continue reading...

Problem

How to implement versioning in ASP.NET Core Web API.

Solution

Create an empty project, add NuGet packages:

  • Microsoft.AspNetCore.Mvc.Versioning

Update Startup class to add services and middleware for MVC:

C#
public void ConfigureServices(
            IServiceCollection services)
        {
            services.AddApiVersioning(options =>
            {
                options.ReportApiVersions = true;
                options.AssumeDefaultVersionWhenUnspecified = true;
                options.DefaultApiVersion = new ApiVersion(1, 0);
            });

            services.AddMvc();
        }

        public void Configure(
            IApplicationBuilder app, 
            IHostingEnvironment env)
        {
            app.UseDeveloperExceptionPage();
            app.UseMvcWithDefaultRoute();
        }

Add controllers for different versions that can be accessed via query string:

C#
/movies?api-version=2.0

    [ApiVersion("1.0")]
    [Route("movies")]
    public class MoviesControllerV1 : Controller
    {
        [HttpGet]
        public IActionResult Get() => Content("Version 1");
    }

    [ApiVersion("2.0")]
    [Route("movies")]
    public class MoviesControllerV2 : Controller
    {
        [HttpGet]
        public IActionResult Get() => Content("Version 2");
    }

Add controllers for different versions that can be accessed via URL:

C#
/actors/v2.0

    [ApiVersion("1.0")]
    [Route("actors/v{ver:apiVersion}")]
    public class ActorsControllerV1 : Controller
    {
        [HttpGet]
        public IActionResult Get() => Content("Version 1");
    }

    [ApiVersion("2.0")]
    [Route("actors/v{ver:apiVersion}")]
    public class ActorsControllerV2 : Controller
    {
        [HttpGet]
        public IActionResult Get() => Content("Version 2");
    }

Add controllers for different versions that can be accessed via HTTP Header:

C#
/reviews

    [ApiVersion("1.0")]
    [Route("reviews")]
    public class ReviewsControllerV1 : Controller
    {
        [HttpGet]
        public IActionResult Get() => Content("Version 1");
    }

    [ApiVersion("2.0")]
    [Route("reviews")]
    public class ReviewsControllerV2 : Controller
    {
        [HttpGet]
        public IActionResult Get() => Content("Version 2");
    }

You can pass header using Postman:

Discussion

As your Web API changes, you would need to add versioning support in order for clients to continue working correctly. Adding versioning support in ASP.NET Core involves first configuring services in Startup and then choosing a versioning strategy, i.e., via query string, URL or HTTP header.

Note: I prefer using HTTP headers to supply version number as it keeps the URL free of clutter, however, you could choose option better suited for your needs.

Configuring Services

During configuration, you could set the following properties:

  • ReportApiVersions: Adds a response header api-supported-versions
  • AssumeDefaultVersionWhenUnspecified: Clients that don’t specify version, default will be used, otherwise they will get an error (UnsupportedApiVersion)
  • DefaultApiVersion: Specify default version number using ApiVersion
  • ApiVersionReader: Specify the location from where version v is read. The default is query string however, to use HTTP header, you need to specify this (see section below).
  • Conventions: Instead of using [ApiVersion] attribute, you could specify versions of various controllers here (see section below).

Note: You could read the current version of request by using GetRequestedApiVersion method on HttpContext, which returns ApiVersion type.

Query String

The default method of specifying version number is via query string api-version parameter.

URL

You could use a route and apiVersion constraint to specify version number in the URL. Note that specifying version in query string will no longer work (it will be ignored since the route will hit a specific controller):

C#
[ApiVersion("2.0")]
    [Route("actors/v{ver:apiVersion}")]
    public class ActorsControllerV2 : Controller

HTTP Header

To use HTTP headers to pass in version number, you need to first configure the version reader, which tells the middleware how to read version. Once this option is configured, specifying version in query string won’t work:

C#
options.ApiVersionReader = new HeaderApiVersionReader("api-version");

Note that you can choose the header key however, I’ve used “api-version” just to keep it consistent with query string and URL based methods.

Conventions

Instead of using [ApiVersion] attribute, you could configure version numbers on controllers by using Conventions property:

C#
options.Conventions.Controller<WritersControllerV1>()
                    .HasApiVersion(new ApiVersion(1, 0));

                options.Conventions.Controller<WritersControllerV2>()
                    .HasApiVersion(new ApiVersion(2, 0));

Now the controllers don’t need any extra attributes:

C#
[Route("writers")]
    public class WritersControllerV1 : Controller
    {
        [HttpGet]
        public IActionResult Get() => Content("Version 1");
    }
    
    [Route("writers")]
    public class WritersControllerV2 : Controller
    {
        [HttpGet]
        public IActionResult Get() => Content("Version 2");
    }

Versioning Action Methods

You could also version action methods within a controller using [MapToApiVersion] attribute:

C#
[ApiVersion("1.0")]
    [ApiVersion("2.0")]
    [Route("directors")]
    public class DirectorsController : Controller
    {
        [HttpGet]
        public IActionResult Get() => Content("Version 1");

        [HttpGet, MapToApiVersion("2.0")]
        public IActionResult GetV2() => Content("Version 2");
    }

Deprecating Versions

You could specify whether a version of API is deprecated by setting Deprecated property on the [ApiVersion] attribute:

C#
[ApiVersion("1.0", Deprecated = true)]
    [Route("genres")]
    public class GenresControllerV1 : Controller
    {
        [HttpGet]
        public IActionResult Get() => Content("Version 1");
    }

    [ApiVersion("2.0")]
    [Route("genres")]
    public class GenresControllerV2 : Controller
    {
        [HttpGet]
        public IActionResult Get() => Content("Version 2");
    }

Note that this doesn’t stop clients from using the version and will only output response headers:

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Share

About the Author


Comments and Discussions

 
Questionhow to add version as 1.0.1 Pin
Member 1372936115-Mar-18 19:41
MemberMember 1372936115-Mar-18 19:41 
GeneralThanks for sharing this article Pin
Alireza_13629-Jan-18 3:39
MemberAlireza_13629-Jan-18 3:39 
QuestionVery clear Pin
Member 1056055623-Nov-17 0:36
professionalMember 1056055623-Nov-17 0:36 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.