On Mon, Jan 9, 2012 at 4:33 AM, Salvatore Orlando < salvatore.orla...@eu.citrix.com> wrote:
> Hi all,**** > > Here’s another “resurrecting” email thread, after exactly a month! > just in time! everyone knows that email thread expire after one month. I agre with your thoughts below and don't really have anything to add. Are we to the point where we should create a BP for this? Dan > **** > > ** ** > > 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> 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] > *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**** > > twitter: danwendlandt > ~~~~~~~~~~~~~~~~~~~~~~~~~~~**** > > **** > > **** > > > > **** > > ** ** > > -- > ~~~~~~~~~~~~~~~~~~~~~~~~~~~ > Dan Wendlandt **** > > Nicira Networks: www.nicira.com**** > > twitter: danwendlandt > ~~~~~~~~~~~~~~~~~~~~~~~~~~~**** > > ** ** > -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Dan Wendlandt Nicira Networks: 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
