Hi Aaron, The error codes returned by the Quantum API were one of the most discussed points in the diablo release cycle. I reckon I changed them at least 4 times!
Let me first give you some background. The choice was between using HTTP response codes capable of easily pointing the user to the root cause or using only standard HTTP response code, embedding application-level error codes (e.g.: NetworkNotFound) within the response itself. We decided to follow the first option, provisioned that we ensured no error code chosen for Quantum redefined any standard HTTP error code. Personally, I think both approaches are perfectly valid; however I realize the approach we chose is probably not the 'standard' way of implementing RESTful APIs. I'm therefore completely open at restructuring Quantum's response codes, and target this work for E-3 provided that i) there's agreement from the community (meaning that nobody has a strong argument against it) and ii) we agree on how to deal with the resulting incompatibility between v1.0 and v1.1. I also think we are summarizing pretty well how we could restructure the error codes: · 420, 430 --> 404 · 421, 432, 440 --> 409 · 431 (RequestedStateInvalid) could also be mapped on 409. It is not a 5xx case, as this error is generated when an invalid administrative state is specified in the request (invalid means that its syntax is invalid, not that the server does not consider it valid due to its current state) · For the Unauthorized error, the discussion on the WWW-Authenticated header probably goes beyond Quantum, as I think it involves each Openstack project integrated with Keystone. In case we decide to restructure the error code another thing we might consider is to use 400 BADREQUEST (and 401 for auth failures) only, including the Quantum-specific error code in the response. IMHO This would also be along the same lines of what Aaron suggested, and possibly easier for client apps which will not have to look for multiple error codes in the HTTP response. Regards, Salvatore From: Aaron Lee [mailto:aaron....@rackspace.com] Sent: 06 December 2011 22:42 To: netstack@lists.launchpad.net Cc: Salvatore Orlando; Dan Wendlandt Subject: Re: error codes in quantum api Dan, Salvatore, folks, The issue I've seen with this was an error in quantum that raised an unexpected error within nova, causing a 500 to bubble back to the api. It was a miss configuration that caused the initial error, but it could have occurred in the wild as well. This will occur for other consumers of this API as well. We can expect at lest some of them to use HTTP or REST libraries that don't know what to do with non-standard HTTP error codes. I think it would be nicer to those people to use the most specific, yet IETF defined, error code possible. We can include a more specific message within response, but it should conform to an expected(and hopefully handled by their libraries) error code. The idea I'm promoting here is the element-of-least-surprise. If someone were rolling their own http client, it may be cute to see custom codes, but I don't think most people will be doing that. It could be off putting for them to have to pick a different library just because of these codes. As far as how to change them; I'm not sure what to do with 401, rfc 2661 says this "response MUST include a WWW-Authenticate header field (section 14.47) containing a challenge applicable to the requested resource." And I'm not sure we always do that. For authentication and authorization I would recommend we remain consistent with the rest of openstack. For NetworkNotFound 420, and PortNotFound 430 I recommend we replace these with 404. We can have a more specific message about the exact missing resource in the response. NetworkInUse 421, PortInUse 432, and AlreadyAttached 440 seem like good candidates for 409 Conflict. 409 requires the response to include enough information to identify the source of the conflict, and I believe this would satisfy the original idea of being more specific for the users of this API. RequestedStateInvalid 431 I'm not 100% sure what to do about this one. It almost seems like it would be a 5xx-opps-I'm-sorry instead of a 4xx-no-you'r-wrong because it's a missing feature. But I would be afraid of a client that handles 5xx response different from 4xx ones. Following least surprise it could be 501, Not Implemented. However I don't see a 4xx error code that would express this. Please let me know what you think, Aaron Lee On Dec 6, 2011, at 3:58 PM, Dan Wendlandt wrote: Hi folks, One quick of the Quantum API that is potentially confusing is that we use non-standard HTTP error codes to provide specialized error codes. For example, instead of a 404 for any not found, we have 420 for "network not found" and 430 for "port not found". This could be potentially useful if the exact item that could not be found is not implicit in the actual API call (e.g., if I query port Y on network X, it could be either the network or the port that was not found). I'm not sure if that was the original intent fo the design, but that's my guess. Given that we're close to defining a new rev of the API, Aaron suggested that we open a discussion on the topic, so I'm doing just that. Please jump in. Dan -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Dan Wendlandt Nicira Networks: www.nicira.com<http://www.nicira.com/> twitter: danwendlandt ~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- Mailing list: https://launchpad.net/~netstack Post to : netstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~netstack More help : https://help.launchpad.net/ListHelp
