btw, based on discussion at the netstack meeting yesterday, we're going to go forward with this.
Salv, always a gent, volunteered to create and take on the following BP: https://blueprints.launchpad.net/quantum/+spec/api-error-codes This is targeted for E-3, which means feedback on spec will have to be quick. Earlier in this thread I throw out one option for how to map existing error codes to more standard codes. There are probably other approaches as well. Dan On Tue, Jan 10, 2012 at 1:37 PM, Dan Wendlandt <d...@nicira.com> wrote: > > > 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 > ~~~~~~~~~~~~~~~~~~~~~~~~~~~ > > -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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
