6.3.0

This is a minor update, which includes some routing improvements.

Features

All Platforms

• ApiVersioningOptions.UnsupportedApiVersionStatusCode has been added to indicate the status code used when an API version doesn't match
  • The default value is 400, which has been the de facto from the beginning
  • Any status code can be used, but 400, 404, or 501 are generally the ones that make sense
  • Each response will continue to include ProblemDetails, which is always the same; regardless of status code
  • When versioning exclusively by URL segment or the incoming request URL is determined to yield an API version route parameter, this option is ignored and the response will always be 404
• A Sunset Policy will always attempt be written when reporting API versions
  • Previously, it was only written on success because success is required for API-specific policies
  • A version-specific policy can be written even during failure since it is related to the version as a whole, regardless of API

Fixes

ASP.NET Core

• IApiVersioningBuilder.AddMvc and IApiVersioningBuilder.AddApiExplorer now ensure dependent services are registered
  • AddApiExplorer, in particular, snagged a number of people that didn't realize they needed AddMvc
• The ProblemDetails.Code extension is now correctly written in JSON as code
• API versions are now reported when an endpoint is unmatched (#876, #918)
  • This should restore the behavior for unmatched endpoints that existed prior to 6.0
  • This is a best effort
    • No erroneous scenarios have been found, but there could be edge cases
    • The behavior is relying on the routing system to collate the metadata from endpoints that are already collated by name using their route templates
    • Attempts to create contrived configurations that could yield incorrect results were unsuccessful (which is good)

Breaking Changes

Restoring the unmatched endpoint behavior may break the expectations for those that have adopted 6.0. There's no good answer or time for this change to occur since this is an implementation detail that only manifests in behavior. Despite calling out the changes in the roadmap and release notes, several issues have been filed related to the change in 6.0. At the time, it didn't seem possible to retain that functionality, but it seems that - largely - it can be.

Ultimately, this change only affects APIs that are strictly concerned about whether the response will be 400 or 404 for client errors on unmatched versions. 400 will now revert to be the default case where you might have received 404. If it's important to you to retain the behaviors you've established while adopting 6.x, you can achieve that by setting:

ASP.NET Web API

(ApiVersioningOptions options) => options.UnsupportedApiVersionStatusCode = HttpStatusCode.NotFound

ASP.NET Core

(ApiVersioningOptions options) => options.UnsupportedApiVersionStatusCode = 404

Special note for .NET Core 3.1 users. There are edge cases where 404 is returned instead of 400. In reviewing the test cases, this was already a problem. It's unclear why that happens, but it appears to be a change or fix in the routing system in at least .NET 6.0 and above. This will be considered the expected behavior. It may be possible to change the behavior with middleware.