Open Stack

I discussed this with Mark on IRC. I think the issue of what API 
compatibility means is very tricky. The need to weigh API consistency 
and implementation changes that
improve the code against pain caused to operators and users is always a 
judgement call. There need to be written guidelines for what kinds of 
changes are acceptable or not acceptable in the context of keeping the 
same API version number just as there are (actually similar) guidelines 
for accepting changes to stable/essex. Even with
guidelines, judgement calls will have to be made. Some more comments 
inline. Note that this issue came to light because a Tempest test failed 
as a result of a code change.

Obviously it is my view that we should take a pretty hard line when it 
comes to changing return codes or json attributes, documented or not, 
and that
repairing API consistency should be left to new versions of the API. 
Others may differ.

Beyond that, there is the question of what the "type signature" of an 
OpenStack API actually means. Does it include the HTTP return code? As 
detailed below, the answer is mixed but this should be consistent across 
all OpenStack APIs. In short, what does it really mean to say that an 
operator is supporting version "x" of OpenStack API "y"?

  -David

On 7/23/2012 5:15 AM, Mark McLoughlin 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.
> I agree. I'm fully behind us being very careful about maintaining API
> compatibility, but that does not imply that we should prevent ourselves
> from fixing bugs until a v3 API.
>
> So, some things I'd consider when reviewing the change:
>
>    - do we document anywhere what our response codes should be for
>      resource creation? (guess: no)
There is wide variation here:

Swift -- documents return codes
Nova -- "core" apis document return codes, many "extensions" do not
Glance -- seems to not document them
Keystone -- documents return codes
Quantum -- documents return codes

>
>    - if not, is 201 with a Location header the right thing? (guess: yes)
Probably so.
>
>    - do we know of any clients that this change would break? (guess: no)
We have know way of knowing what applications using OpenStack apis are 
doing but I don't think
that means we can assume none would break.
>
> Also, the "we must maintain compat" is inconsistent with other similar
> changes like this one merged on Friday:
>
>    https://review.openstack.org/#/c/9993/

I can see that. We need to decide whether this sort of thing is OK.
>
> Cheers,
> Mark.
>
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev