Hi all, Here's another "resurrecting" email thread, after exactly a month!
Aaron had a very interesting observation concerning error codes raised from the Quantum API. We currently use several 4xx codes to describe Quantum-specific errors, such as "NetworkNotFound" or "PortNotFound"; we ensured that Quantum error codes did not overlap with standard HTTP error codes. Even if this simplifies the process of understanding the reason of the failure of an API operation, on the other hand it might create problems for clients using standard REST libraries which expect only standard HTTP codes; also this is not compliant with the current implementation of the Openstack API; to the best of my knowledge, Keystone and Glance API too only use standard HTTP error codes; I'm not sure about swift, but I think it also uses standard codes only. It is my opinion that, in order to proceed in the right way on error code, we should answer the following three questions: 1) Do we want to change the error codes at all? - and if yes, when. 2) How do we want to restructure them? 3) How do we handle the difference between Quantum API v1.0 and v1.1? Personally, my answers are: 1 - If being compliant with APIs for core OS projects is a priority for us, then yes, we should definitely change the structure of the error codes; the sooner we do it, the better it is; 2 - The OS API approach (I'm referring API spec 1.1 for an example, I don't know whether there are changes in error codes for API 2.0) "maps" the fault to the HTTP error codes which semantically closer to the fault. For instance, "buildinprogress" is mapped to HTTP 409 - which is used for expressing a conflict error. Even though we could follow this approach, it is my opinion that we could just use a few error codes (namely 400, 401, and 403) and then embed a Quantum-specific code, and a detailed error message in the response body. 3 - That's a very delicate point, but I reckon we should leave the current error codes in v1.0, and provide the new ones in v1.1. This would definitely break backward compatibility for clients written for API v1.0; hence we should also consider branding this new version 2.0. What are your thoughts? Regards, Salvatore From: Dan Wendlandt [mailto:d...@nicira.com] Sent: 09 December 2011 02:13 To: Salvatore Orlando Cc: Aaron Lee; netstack@lists.launchpad.net Subject: Re: error codes in quantum api On Wed, Dec 7, 2011 at 7:29 AM, Salvatore Orlando <salvatore.orla...@eu.citrix.com<mailto:salvatore.orla...@eu.citrix.com>> wrote: 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) I think this generally makes sense, going by the two measuring sticks of "least surprise" and "most like other openstack projects". and ii) we agree on how to deal with the resulting incompatibility between v1.0 and v1.1. As long as this is part of a version change, and the client is updated, I don't think this will be a big deal, right? My bigger concern is to see who is volunteering for the work... are you interested Aaron? I know Salv is already quite loaded with work for E-2 and E-3. I also think we are summarizing pretty well how we could restructure the error codes: * 420, 430 --> 404 * 421, 432, 440 --> 409 Definitely agree with the above mappings. * 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) Agreed that this is not really a 5xx error. This is a case of a "bad user input", where a certain text string named "state" in the JSON or XML body should be one of a few well-defined values (either "DOWN" or "ACTIVE") otherwise we return an error code. In my experience, usually a 409 is used the request is syntactically "valid" but being rejected because it violates some constraint in the resource model. This is more of a case of "this request is not valid syntax". For this, the vanilla 400 error seems applicable. The RFC text is: "The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications." That said, I don't really feel strongly about this :) * 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. Agreed. 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. That's a fair point. I tend to like using 404s and 409s as well, as it allows some differentiation (e.g., I can programmatically tell the difference between a valid request for an entity that doesn't exist and an invalidly formated request. I might want to react to them differently. In the first case, perhaps I perform some action to create the entity. In the latter, I probably just log something and give up.) Dan Regards, Salvatore From: Aaron Lee [mailto:aaron....@rackspace.com<mailto:aaron....@rackspace.com>] Sent: 06 December 2011 22:42 To: netstack@lists.launchpad.net<mailto: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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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
