Open Stack

On Wed, 2012-07-25 at 13:49 -0400, Sean Dague wrote:
> 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 don't know of any complete existing documentation of these.

If we could gather together some thoughts on what they should be, this
could form the beginning of discussing and documenting what changes
should be made in v3.

It would actually be a really worthwhile discussion to have - e.g. I
think we misuse/abuse/overuse "202 Accepted" and that "201 Created" is
usually more appropriate.

> >     - 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?

Not that I know of. How could we do this? A v3-api blueprint with most
of the details in a wiki page? And also a v3-api tag for bugs which
we're deferring until v3?

> > 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.

Ok, I can buy that response codes are just about above our current
"client impact threshold". Especially if we have some sort of realistic
plan for cleaning these up in the medium term.

In v3, though, it would be worth considering explicitly calling out that
individual response codes as something that clients should not
explicitly rely on - i.e. "accept 2xx as success".

Cheers,
Mark.