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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- Mailing list: https://launchpad.net/~netstack Post to : netstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~netstack More help : https://help.launchpad.net/ListHelp
