Skip to content

Versioning by Header

Jump to bottom
Chris Martinez edited this page Dec 29, 2022 · 2 revisions

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 with MVC (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;
    }
}

ASP.NET Core with MVC (Core)

var hello = app.NewVersionedApi();

hello.MapGet( "/helloworld", () => "Hello world!" ).HasApiVersion( 1.0 );

Configuration

ASP.NET Web API and ASP.NET Core would 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/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!
Clone this wiki locally