Versioning via the URL Path

An alternate, but common, method of API versioning is to use a URL path segment. This approach does not allow implicitly matching the initial, default API version of a service; therefore, all API versions must be explicitly declared. In addition, the API version value specified for the URL segment must still conform to the version format. The v prefix is not part of the API version, but may be included in route templates if you so desire.

Note: It is not possible to have a default API version for a URL path segment. This means that setting ApiVersioningOptions.AssumedDefaultVersionWhenUnspecified is unlikely to have any affect when you use this method of versioning. For more information and possible solutions to address this scenario, refer to the known limitations.

ASP.NET Web API

public static class WebApiConfig
{
    public static void Configuration( HttpConfiguration configuration )
    {
        var constraintResolver = new DefaultInlineConstraintResolver()
        {
            ConstraintMap =
            {
                ["apiVersion"] = typeof( ApiVersionRouteConstraint )
            }
        };
        configuration.MapHttpAttributeRoutes( constraintResolver );
        configuration.AddApiVersioning();
    }
}

[ApiVersion( 1.0 )]
[Route( "api/v{version:apiVersion}/helloworld" )]
public class HelloWorldController : ApiController
{
    public string Get() => "Hello world!";
}

[ApiVersion( 2.0 )]
[ApiVersion( 3.0 )]
[Route( "api/v{version:apiVersion}/helloworld" )]
public class HelloWorld2Controller : ApiController
{
    public string Get() => "Hello world v2!";

    [MapToApiVersion( 3.0 )]
    public string GetV3() => "Hello world v3!";
}

ASP.NET Web API and OData

Since the OData implementation uses convention-based routes under the hood, the ApiVersionRouteConstraint is automatically added to all versioned OData routes when needed. The name of the constraint used in prefixes of OData routes must be apiVersion and cannot be changed.

public static class WebApiConfig
{
    public static void Configuration( HttpConfiguration configuration )
    {
        var modelBuilder = new VersionedODataModelBuilder( configuration )
        {
            ModelConfigurations =
            {
                new PersonModelConfiguration()
            }
        };

        configuration.AddApiVersioning();
        configuration.MapVersionedODataRoutes( "odata-bypath", "api/v{apiVersion}", modelBuilder );
    }
}

[ApiVersion( 1.0 )]
[ODataRoutePrefix( "People" )]
public class PeopleController : ODataController
{
    [EnableQuery]
    [ODataRoute]
    public IQueryable<Person> Get() => new[]{ new Person() }.AsQueryable();
}

[ApiVersion( 2.0 )]
[ApiVersion( 3.0 )]
[ControllerName( "People" )]
[ODataRoutePrefix( "People" )]
public class People2Controller : ODataController
{
    [EnableQuery]
    [ODataRoute]
    public IQueryable<Person> Get() => new[]{ new Person() }.AsQueryable();

    [EnableQuery]
    [ODataRoute, MapToApiVersion( 3.0 )]
    public IQueryable<Person> GetV3() => new[]{ new Person() }.AsQueryable();
}

ASP.NET Core with MVC (Core)

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

[ApiVersion( 2.0 )]
[ApiVersion( 3.0 )]
[ApiController]
[Route( "api/v{version:apiVersion}/helloworld" )]
public class HelloWorld2Controller : ControllerBase
{
    [HttpGet]
    public string Get() => "Hello world v2!";

    [HttpGet, MapToApiVersion( 3.0 )]
    public string GetV3() => "Hello world v3!";
}

ASP.NET Core with OData

[ApiVersion( 1.0 )]
public class PeopleController : ODataController
{
    [EnableQuery]
    public IQueryable<Person> Get() => new[]{ new Person() }.AsQueryable();
}

[ApiVersion( 2.0 )]
[ApiVersion( 3.0 )]
[ControllerName( "People" )]
public class People2Controller : ODataController
{
    [EnableQuery]
    [ODataRoute]
    public IQueryable<Person> Get() => new[]{ new Person() }.AsQueryable();

    [EnableQuery]
    [ODataRoute, MapToApiVersion( 3.0 )]
    public IQueryable<Person> GetV3() => new[]{ new Person() }.AsQueryable();
}

var builder = WebApplication.CreateBuilder( args );

builder.Services.AddControllers().AddOData();
builder.Services.AddProblemDetails();
builder.Services.AddApiVersioning().AddOData(
    options =>
    {
        options.ModelBuilder.DefaultModelConfiguration = ( builder, apiVersion, routePrefix ) =>
        {
            builder.EntitySet<Person>( "People" );
        };
        options.AddRouteComponents( "api/v{version:apiVersion}" );
    } );

var app = builder.Build();

app.MapControllers();
app.Run();

The effect of the API version attribution is that the following requests match different controller implementations:

Request URL	Matched Controller	Matched Action
/api/v1/helloworld	HelloWorldController	Get
/api/v2/helloworld	HelloWorld2Controller	Get
/api/v3/helloworld	HelloWorld2Controller	GetV3
/api/v1/People	PeopleController	Get
/api/v2/People	People2Controller	Get
/api/v3/People	People2Controller	GetV3

ASP.NET Core with Minimal APIs

var builder = WebApplication.CreateBuilder( args );

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

var app = builder.Build();
var people = app.NewVersionedApi();
var v1 = people.MapGroup( "/people/v{version:apiVersion}" ).HasApiVersion( 1.0 );

v1.MapGet( "/", () => new[] { new Person() } );

app.Run();