All 15 API Versioning questions
More in API Versioning
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 does ASP.NET Core API versioning handle a request that doesn't specify any version at all? How would you design API versioning strategy differently for a public, third-party-consumed API versus an internal microservice API? How do you combine multiple version reader strategies (e.g., both URL segment AND header) to give clients flexibility in how they specify a version? How would you implement automated testing that verifies deprecated API versions still function correctly while newer versions are actively developed?
Advertisement
ASP.NET Core › API Versioning

How do you deprecate an API version gracefully, notifying consumers via response headers before eventually removing it?

Advanced

Answer

Marking a version with [ApiVersion("1.0", Deprecated = true)] combined with options.ReportApiVersions = true causes the middleware to automatically include api-deprecated-versions and api-supported-versions response headers on every response, giving automated tooling or attentive client developers a machine-readable signal of the impending removal well before the version is actually deleted from the codebase.
[ApiVersion("1.0", Deprecated = true)]
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/orders")]
public class OrdersController : ControllerBase { }

// Every response now includes:
// api-deprecated-versions: 1.0
// api-supported-versions: 1.0, 2.0
Real-world example A partner integration team's automated monitoring watches the api-deprecated-versions header on every API call, automatically opening an internal ticket when their integration is detected still using a version flagged as deprecated, well ahead of its actual removal date.

Common follow-ups: How long is a reasonable deprecation window before removing a version entirely?;How would you notify consumers through channels beyond just response headers?

RESTful Web APIs & Controllers;Logging
All 15 API Versioning questions