All 15 API Versioning questions
More in API Versioning
Why is API versioning important for a production web API? What are the main strategies for versioning an ASP.NET Core API (URL, query string, header, media type)? How do you communicate API version deprecation to clients using response headers? How does semantic versioning (SemVer) inform decisions about when to bump an API's major, minor, or patch version? How do you version an API's OpenAPI/Swagger documentation to show separate docs per version? How does GraphQL's approach to API evolution differ from REST's typical versioning strategies? What HTTP status code and response should an API return when a client requests a version that no longer exists or was never supported? How can feature flags be used as an alternative or complement to formal API versioning for rolling out changes gradually? How can you version a single controller action to support multiple API versions without duplicating the entire controller class? What's the difference between versioning a REST API's contract versus versioning its underlying data model, and why does that distinction matter?
Advertisement
.NET › API Versioning

How do you implement URL-based API versioning using the Asp.Versioning.Mvc package in ASP.NET Core?

Intermediate

Answer

The Asp.Versioning packages (successor to Microsoft.AspNetCore.Mvc.Versioning) let you register API versioning services, define supported versions per controller/action via [ApiVersion] attributes, and use a {version:apiVersion} route template placeholder so the framework automatically routes requests to the correct versioned controller or action.
builder.Services.AddApiVersioning(options => {
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
});

[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/products")]
public class ProductsV1Controller : ControllerBase { }

[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/products")]
public class ProductsV2Controller : ControllerBase { }
Real-world example An e-commerce API adds a ProductsV2Controller alongside the existing V1 controller when the product schema needs a breaking change, letting both versions run simultaneously in production.

Common follow-ups: How do you deprecate a version and communicate it via response headers?;How does versioning interact with Swagger/OpenAPI documentation generation?

ASP.NET Core Middleware & Request Pipeline;RESTful Web APIs & Controllers
All 15 API Versioning questions