[openstack-dev] [API] Standardizing status codes in the native API

David Kranz david.kranz at qrclab.com
Mon Jul 23 00:27:41 UTC 2012


Eoghan, I think your suggestion is reasonable but will let others 
comment. I hope you don't think I was too strident in my response which 
was not meant to call you out in particular. This issue was the bane of 
my existence in the last project I led and your email seemed like a good 
starting point to start getting every one on the same page about what 
kinds of changes are or are not acceptable. I would not be surprised to 
see some others objecting to the full implications of my comment. Having 
real users is a pain :-) .

  -David


On 7/22/2012 12:39 PM, Eoghan Glynn wrote:
>
>>>> Agreed, I expect a number of clients are checking for 200, and not
>>>> a
>>>> generic 2xx status code. So, while I am all in favor of this
>>>> change,
>>>> I think it requires a version bump.
>>> Thanks Jay&  Sean for the responses,
>>>
>>> Normally I'd agree with you that we need to very reticent about
>>> breaking
>>> backward compatibility, however in this case I suspect we may be
>>> talking
>>> about bug compatibility.
>>>
>>> The way the code is structured (defaulting to a 200 response code,
>>> as
>>> opposed to setting this explicitly) and the fact that some other
>>> native
>>> APIs return 202 on resource creation, led to me to believe that the
>>> current behavior may be the result of an over-sight as opposed to a
>>> deliberate choice.
>> That may well be the case but I don't think it matters. The point of
>> maintaining API compatibility for
>> a specific version is that applications using the OpenStack APIs will
>> not break when an operator upgrades to
>> a new version of OpenStack (Folsom, Grizzly, etc.) that supports that
>> same API version. Also that applications should work across any
>> OpenStack implementation supporting the particular API version.
>>
>> This has nothing to do with code organization, consistency with other
>> APIs, or whether developers think some aspect of the existing API is
>> bad. If a code change causes Tempest tests to fail, or could break
>> any
>> correctly working application, it is probably an unacceptable API
>> change. An API change cannot be allowed without bumping the version
>> number. I think the only exception to this would be if an API change
>> was
>> necessary to fix a security bug.
>>
>> Also, with regard to compatibility, it makes no difference what some
>> spec says if it is different from what the code does. Changing the
>> code
>> to conform to the "spec" should still require a version bump if it
>> would
>> break existing applications.
>>
>> Finally, I don't understand why the behavior of things like
>> novaclient
>> matters at all with regard to this issue. The OpenStack API is the
>> HTTP
>> API, not the clients. The fact that a client could be modified to
>> accommodate both old and new behavior does not mean it is not an API
>> change that will break applications using the OpenStack APIs.
> OK, I've modified the patch in question to leave the status code
> as-was, but to go ahead and add a Location header - this being a
> purely additive change, it should be safe (i.e. I can't image any
> clients relying on the *absence* of a header).
>
> In general, do we have any way of tracking the backlog of API "fixes"
> that are awaiting the next major version?
>
> Also is there a v3 compute API on the horizon, or is that just
> something that will come into focus when we have accumulated enough
> reasons to change the current API?
>
> Cheers,
> Eoghan
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev





More information about the OpenStack-dev mailing list