Versioning ASP.NET Core 2.0 Web API

Problem

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

Solution

Create an empty project, and add the following NuGet package.

  • Microsoft.AspNetCore.Mvc.Versioning

Update the Startup class to add services and middleware for MVC.

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

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

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

You can pass the 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 the 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: For clients that don’t specify the version, the 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 a 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 the request by using the 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 the version number in the URL. Note that specifying the version in query string will no longer work (it will be ignored since the route will hit a specific 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 the version in query string won’t work:


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.

Now, the controllers don’t need any extra attributes.

Versioning Action Methods

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

Deprecating Versions

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

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

Source Code

GitHub