Open Stack

On 07/25/2012 12:39 PM, Mark McLoughlin wrote:
>     - Our API documentation doesn't cover every aspect of the API which
>       clients may come to rely on. We also don't really document what
>       clients should avoid relying on (e.g. URL structure, specific
>       response codes etc.) so we can't always rely on the documentation
>       to tell us whether an API fix is acceptable.

I'm actually trying to sort out how and where we are documenting these 
details today in a user facing way, and what we consider canonical on 
return codes? This seems a bit fragmented today, as I was trying to 
figure out what we specified in the v2 API fully here.

>     - I hate to think of us rejecting API fixes with "this needs to wait
>       until v3" and then, when v3 comes around, we don't actually get
>       around to fixing those issues. We need some way of channelling
>       people's desire to fix the API, even if that's just helping to
>       document what needs fixing in v3.

Agreed. Is there some kind of artifact in launchpad that we can track to?

> So, thinking about this specific issue:
>
>     - "201 Created" is clearly the right behaviour and is what we do
>       elsewhere in the API. Unfortunately, we don't document this so we
>       can't just say "see, we're just making it compliant with the spec".
>
>     - Some clients may be relying on "200 OK" and they may be affected
>       by this change. However, more sensible clients would just accept
>       any 2xx code as success. In terms of impact that I expect API
>       clients may see between Essex and Folsom, my guess is this is
>       pretty minor.
>
>     - I don't know of any plans for v3. I also don't know that we have
>       any way to channel this effort into preparing for v3.
>
> No-one reading this should interpret it as a lack of understanding of
> the importance of API compatibility. There is a spectrum of API compat
> strictness. Where we fall on the spectrum at this point of the project's
> life isn't a trivial question. We don't want to be at either of the
> extreme ends of the spectrum (e.g. the rules Sun used to apply to
> Solaris changes vs Ruby libraries which change API every day of the
> week), so please don't try and make out this is a black-and-white thing.

I agree that it's not black and white, but the fact that this required a 
change in tempest should be an indication that == 200 is a common 
pattern for folks, ourselves included. So there are some real pragmatics 
about changing what a success code is.

	-Sean

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