All 15 API Versioning questions
More in API Versioning
Why does an ASP.NET Core Web API need explicit versioning support, and what package provides it? What does the ReportApiVersions option do, and what response headers does it add? How do you implement URL segment-based API versioning for controllers using [ApiVersion] and route templates? How does header-based API versioning work, and what's a scenario where it's preferred over URL segment versioning? How do you unit test that a specific API version's controller action behaves correctly, given the version-based routing? How does query string-based API versioning work, and what are its trade-offs compared to URL segment versioning? How do you handle API versioning for gRPC services, given gRPC's contract is defined via .proto files rather than URL routes? How do you configure a sunset date for a deprecated API version so clients receive a clear removal timeline? How do you implement API versioning for minimal API endpoints, since they don't use controller attributes? How do you deprecate an API version gracefully, notifying consumers via response headers before eventually removing it?
Advertisement
ASP.NET Core › API Versioning

What is the difference between versioning at the API level (entire controller/group) versus versioning individual actions within a shared controller?

Intermediate

Answer

API-level versioning applies one or more [ApiVersion] attributes to the whole controller, meaning every action in it is available under all declared versions unless individually restricted. Action-level versioning uses [MapToApiVersion("x.0")] on specific actions within a multi-version controller to indicate that action only exists in that particular version, letting most actions be shared across versions while only the actually-changed ones are duplicated.
[ApiVersion("1.0")]
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/products")]
public class ProductsController : ControllerBase {
    [HttpGet]
    public IActionResult GetAll() => Ok(_products);  // available in both 1.0 and 2.0

    [HttpGet("{id}/reviews")]
    [MapToApiVersion("2.0")]
    public IActionResult GetReviews(int id) => Ok(_reviews);  // only in 2.0
}
Real-world example A products API adds a new reviews sub-resource only in v2 using MapToApiVersion, while the existing GetAll and GetById actions remain shared across both versions in the same controller, minimizing duplicated code.

Common follow-ups: What happens if MapToApiVersion references a version not declared on the controller?;When does splitting into fully separate controllers become clearer than this shared approach?

Controllers vs Minimal APIs;Endpoint Metadata Route Constraints & Templates
All 15 API Versioning questions