Return 405 Method Not Allowed for requests that do not support the http method

[mmikulicz]

If an endpoint only supports specific http methods (e.g. POST), and the requested method is not supported (e.g. GET), return status 405 Method Not Allowed with a message similar to The requested resource does not support http method 'GET'.

Example
Api supports: POST to \customers
Request is for: GET to \customers

Current response is 400 Bad Request

{
  "Error": {
    "$type": "system._web._http._http_error",
    "Code": "UnsupportedApiVersion",
    "Message": "The HTTP resource that matches the request URI 'http://localhost/api/v1/customers' does not support the API version '1'.",
    "InnerError": {
      "$type": "system._web._http._http_error",
      "Message": "No route providing a controller name with API version '1' was found to match request URI 'http://localhost/api/v1/customers'."
    }
  }
}

The endpoint does exist for version 1, but the method is incorrect. The current error is a bit misleading for the user.

[commonsensesoftware]

Currently, this is by design and the expected behavior. The rationale is that if a route could match any action for a controller, then it is treated as a possible route. If the action cannot be resolved for the requested version, then you'll get 400 because it's not supported.

While I agree that 405 is more accurate, it can be equally confusing with versioning. Imagine that GET /customers?api-version=1.0 is not supported (your example), but GET /customers?api-version=2.0 is supported. Returning 405 could be interpreted by the client as the method is not supported for any API version. Of course that may not be true and may even be discoverable via OPTIONS /customers?api-version=2.0.

This seems to be quite the gray area and I'm not sure there is a great answer. The Microsoft REST guidelines don't really call out anything specific for this scenario. In older, internal flavors of the guidelines 400 was specifically called out as the response. I don't see anything about that anymore. While I have my own opinion on the matter, my goal is to empower service authors to choose the solution that works best for them. I don't have strong feelings about not using 405.

Let me revisit the matching for actions. There is definitely complexity in sorting out matches that disambiguate between 400 and 405. The end result is still the same behavior with a slightly more informative HTTP status code. I think you should get same error code, but the message might be slightly different.

Adding a new configuration option to control the behavior would also be feasible, but I'd really like to avoid over-configuration. I'd also like see service authors fall into The Pit of Success without a whole bunch of configuration or necessary know how.

Thoughts?

[mmikulicz]

The argument for using 400 makes sense. Additional code complexity & configuration options don't seem like a good solution just to add support for this.

Since 405 seems to be the default response that webapi returns, adding a note in the wiki that versioning returns a 400 for unsupported verbs would be the easiest solution.

[commonsensesoftware]

I think that 405 is the right way to go. Even though it might differ by version, that is the RESTFul way to go. Additionally, it has strong parity with the default behavior. Supporting 405 in this way should be queued up for the next release. I'll leave this open until then,.

[commonsensesoftware]

Circling back around to this - finally. After quite a bit of review, I think is actually a bug. While some strength can be given to my argument, there is nothing really mandating that 400 be used over 405. Since returning 400 instead of a 405 is a behavioral change from the original implementation, I think that is a flaw (after all). Service authors and clients should be able to work under the principle of least astonishment.