Skip to content

Accessing Version Information

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

All of the service API version information is accessible via extension methods. Beginning in version 3.0, Model Binding is also supported. These features allow you to determine which API version was requested by a client as well as determine which versions are supported and deprecated. The API versions provided are automatically aggregated across all service implementations.

The most common usage is the current, client requested API version:

ASP.NET Web API

[ApiVersion( 1.0 )]
[ApiVersion( 2.0 )]
public class MyController : ApiController
{
    public IHttpActionResult Get()
    {
        var apiVersion = Request.GetRequestedApiVersion();
        return Ok();
    }

    // supported in 3.0+
    public IHttpActionResult Get( int id, ApiVersion apiVersion ) => Ok();
}

ASP.NET Core with MVC (Core)

[ApiVersion( 1.0 )]
[ApiVersion( 2.0 )]
[ApiController]
public class Controller : ControllerBase
{
    public IActionResult Get()
    {
        var apiVersion = HttpContext.GetRequestedApiVersion();
        return Ok();
    }

    // supported in 3.0+
    public IActionResult Get( int id, ApiVersion apiVersion ) => Ok();
}

ASP.NET Core with Minimal APIs

Minimal APIs do not currently have parity with Model Binding, but it is possible to receive the incoming API version in the RequestDelegate.

var builder = WebApplication.CreateBuilder( args );

builder.Services.AddProblemDetails();
builder.Services.AddApiVersioning().EnableApiVersionBinding();

var app = builder.Build();
var api = app.NewVersionedApi();

api.MapGet( "/", ( ApiVersion version ) => Results.Ok() )
   .HasApiVersion( 1.0 )
   .HasApiVersion( 2.0 );

app.Run();

If you do not use this capability, then you should avoid calling EnableApiVersionBinding. The way this capability is implemented is expected to change at some point in the future.

Clone this wiki locally