Open Stack

On 07/23/2012 05:15 AM, Mark McLoughlin wrote:
> On Sat, 2012-07-21 at 06:15 -0400, Eoghan Glynn wrote:
>>
>>>>> Do you reckon this change warrants a full major version bump?
>>>>
>>>> Generally speaking non-backwards-compatible changes do require a
>>>> version
>>>> bump, yes. I know it seems like a trivial change, but it would
>>>> break all
>>>> clients expecting a 200 where a 201/202 would now be returned.
>>>
>>> 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)
>
>    - if not, is 201 with a Location header the right thing? (guess: yes)
>
>    - do we know of any clients that this change would break? (guess: no)

This kind of change is more breaking than you think. I've seen a lot of 
web services client code over the years that just does (code == 200) as 
short hand for success. Is it the right thing to do? nope. But it worked 
for people, so is going to be seen as a breaking change by us.

Given that OS API is an external API, I think question 3 is kind of 
irrelevant. We can't assume we know which clients are using it.

> Also, the "we must maintain compat" is inconsistent with other similar
> changes like this one merged on Friday:
>
>    https://review.openstack.org/#/c/9993/

Maybe we need to revisit that?

API uptake only happens if people's code using it doesn't break for 
reasons they don't understand.

	-Sean

-- 
Sean Dague
IBM Linux Technology Center
email: sdague at linux.vnet.ibm.com
alt-email: sldague at us.ibm.com