Versioning by Header

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:

ASP.NET 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;
    }
}

ASP.NET Core

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

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

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

Configuration

ASP.NET Web API and ASP.NET Core would then change the default API version reader as follows:

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/1.1
host: localhost
x-ms-version: 1.0

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

Hello world!