Header Versioning

While media type negotiation is the defined method in REST for reasoning about the content expectations between a client and server, any arbitrary HTTP header can also be used to drive API versioning.

Let’s assume the following controllers are defined:

Web API

namespace Services.V1
{
    [ApiVersion( 1.0 )]
    [RoutePrefix( "api/helloworld" )]
    public class HelloWorldController : ApiController
    {
        [Route]
        public string Get() => "Hello world!";
    }
}

namespace Services.V2
{
    [ApiVersion( 2.0 )]
    [RoutePrefix( "api/helloworld" )]
    public class HelloWorldController : ApiController
    {
        [Route]
        public string Get() => "Hello world!";

        [Route]
        public string Post( string text ) => text;
    }
}

Configuration

The configuration will then change the default API version reader as follows:

.AddApiVersioning( options => options.ApiVersionReader = new HeaderApiVersionReader( "x-ms-version" ) );

This will allow clients to request a specific API version by the custom HTTP header x-ms-version. For example:

GET api/helloworld HTTP/2
host: localhost
x-ms-version: 1.0

HTTP/2 200
host: localhost
content-type: text/plain
content-length: 12

Hello world!