- Notifications
You must be signed in to change notification settings - Fork710
Versioning by Header
Chris Martinez edited this pageDec 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:
namespaceServices.V1{[ApiVersion(1.0)][RoutePrefix("api/helloworld")]publicclassHelloWorldController:ApiController{[Route]publicstringGet()=>"Hello world!";}}namespaceServices.V2{[ApiVersion(2.0)][RoutePrefix("api/helloworld")]publicclassHelloWorldController:ApiController{[Route]publicstringGet()=>"Hello world!";[Route]publicstringPost(stringtext)=>text;}}
namespaceServices.V1{[ApiVersion(1.0)][ApiController][Route("api/[controller]")]publicclassHelloWorldController:ControllerBase{[HttpGet]publicstringGet()=>"Hello world!";}}namespaceServices.V2{[ApiVersion(2.0)][ApiController][Route("api/[controller]")]publicclassHelloWorldController:ControllerBase{[HttpGet]publicstringGet()=>"Hello world!";[HttpPost]publicstringPost(stringtext)=>text;}}
varhello=app.NewVersionedApi();hello.MapGet("/helloworld",()=>"Hello world!").HasApiVersion(1.0);
ASP.NET Web API and ASP.NET Core would then change the default API version reader as follows:
.AddApiVersioning( options=>options.ApiVersionReader=newHeaderApiVersionReader("x-ms-version"));
This will allow clients to request a specific API version by the custom HTTP headerx-ms-version. For example:
GETapi/helloworld HTTP/1.1host: localhostx-ms-version: 1.0
HTTP/1.1 200 OKhost: localhostcontent-type: text/plaincontent-length: 12Hello world!
- Home
- Quick Starts
- Version Format
- Version Discovery
- Version Policies
- How to Version Your Service
- API Versioning with OData
- Configuring Your Application
- Error Responses
- API Documentation
- Extensions and Customizations
- Known Limitations
- FAQ
- Examples