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 implement URL-based API versioning using the Asp.Versioning.Mvc package in ASP.NET Core? 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
Back to results for “RESTful Web APIs & Controllers”
.NET › API Versioning

How do you communicate API version deprecation to clients using response headers?

Intermediate

Answer

The Asp.Versioning library can automatically add an `api-supported-versions` header (listing currently supported versions) and an `api-deprecated-versions` header (listing versions still functional but scheduled for removal) to every response, giving clients a machine-readable way to detect upcoming breaking changes proactively rather than being surprised when a version is finally removed.
builder.Services.AddApiVersioning(options => {
    options.ReportApiVersions = true;  // adds api-supported-versions / api-deprecated-versions headers
});

[ApiVersion("1.0", Deprecated = true)]
[ApiVersion("2.0")]
public class ProductsController : ControllerBase { }
Real-world example A partner integration team writes automated monitoring that checks the api-deprecated-versions header on every API response, automatically filing a ticket when their integration is still using a version flagged as deprecated.

Common follow-ups: How far in advance should deprecation typically be announced?;What HTTP status code should a fully removed version return?

RESTful Web APIs & Controllers;Diagnostics & Performance
All 15 API Versioning questions