- Notifications
You must be signed in to change notification settings - Fork710
Versioning via the Query String
The initial version of a controller may not have any API version attribution and will implicitly become the configured default API version. The default configuration uses the value1.0.
[RoutePrefix("api/helloworld")]publicclassHelloWorldController:ApiController{[Route]publicstringGet()=>"Hello world!";}
[ODataRoutePrefix("People")]publicclassPeopleController:ODataController{[ODataRoute]publicIHttpActionResultGet(ODataQueryOptions<Person>options)=>Ok(new[]{newPerson()});}
[ApiController][Route("api/[controller]")]publicclassHelloWorldController:ControllerBase{[HttpGet]publicstringGet()=>"Hello world!";}
publicclassPeopleController:ODataController{[HttpGet]publicIHttpActionResultGet(ODataQueryOptions<Person>options)=>Ok(new[]{newPerson()});}
To create the next version of the controller, you can choose to create a new controller with the same route, but decorated it as API version2.0. For example:
[ApiVersion(2.0)][RoutePrefix("api/helloworld")]publicclassHelloWorldController:ApiController{[Route]publicstringGet()=>"Hello world!";}
[ApiVersion(2.0)][ControllerName("People")][ODataRoutePrefix("People")]publicclassPeople2Controller:ODataController{[ODataRoute]publicIHttpActionResultGet(ODataQueryOptions<Person>options)=>Ok(new[]{newPerson()});}
[ApiVersion(2.0)][ApiController][Route("api/helloworld")]publicclassHelloWorld2Controller:ControllerBase{[HttpGet]publicstringGet()=>"Hello world!";}
[ApiVersion(2.0)][ControllerName("People")]publicclassPeople2Controller:ODataController{[HttpGet]publicIHttpActionResultGet(ODataQueryOptions<Person>options)=>Ok(new[]{newPerson()});}
The effect of this attribution is that the following requests match different controller implementations:
| Request URL | Matched Controller |
|---|---|
| /api/helloworld?api-version=1.0 | HelloWorldController |
| /api/helloworld?api-version=2.0 | HelloWorld2Controller |
| /api/People?api-version=1.0 | PeopleController |
| /api/People?api-version=2.0 | People2Controller |
It’s important to note that only an undecorated controller will be inferred as the configured, default API version. Once a controller has any API version attribution, it will never be considered as the default API version again unless the API version attribute includes the default API version. This allows you permanently remove API versions over time.
varbuilder=WebApplication.CreateBuilder(args);builder.Services.AddProblemDetails();builder.Services.AddApiVersioning();varapp=builder.Build();varhello=app.NewVersionedApi();varv1=hello.MapGroup("/helloworld").HasApiVersion(1.0);varv2=hello.MapGroup("/helloworld").HasApiVersion(2.0);v1.MapGet("/",()=>"Hello world!");v2.MapGet("/",()=>"Hello world!");app.Run();
- 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