Provide a mechanism to return deprecated and supported version on UnsupportedApiVersion response

[AshishBoobun]

The Report API Versions option returns the supported and deprecated version (in the response header) only if a client requested a "supported version" endpoint. Otherwise, if a "non-supported version" of the API is requested, the default UnsupportedApiVersion is return as follows:

{
    "error": {
        "code": "UnsupportedApiVersion",
        "message": "The requested resource with API version '1' does not support HTTP method 'GET'.",
        "innerError": {
            "message": "No route providing a controller name with API version '1' was found to match HTTP method 'GET' and request URI 'http://blahUrl/api/v1/blaResource'."
        }
    }
}

I guess it is helpful (from a consuming client perspective) to return the api-deprecated-versions and api-supported-versions header when the UnsupportedApiVersion response error is returned?

[commonsensesoftware]

A reasonable request. The reason this happens is because the feature is implemented using an IActionFilter. Since no action is selected in this scenario, the filter is never called. I need evaluate how to make this process work for both paths.

I should point out that your request still doesn't cover all scenarios. For example, your service could support versions 1.0, 2.0, 3.0, but only implements the GET method. If a client sends a POST to any of these versions, they'll receive 405 with the same message, but indicating that 1.0, 2.0, 3.0 are supported. This can be equally confusing. I'm not sure that there is a great solution for that. An API version doesn't convey which HTTP methods are supported.

Better alternatives would be implementing OPTIONS. You can then provide more details specific to a particular API version. For example:

OPTIONS /resource?api-version=1.0 HTTP/1.1
Host: my.site.com
Allow: GET
Api-Supported-Versions: 1.0, 2.0, 3.0

Supporting Swagger would be yet another way to provide this information.

Thanks for the suggestion.