Open Stack

Hey,

Trying to get away from this specific issue for a minute ... some
points:

   - We fix bugs all the time that may affect clients which rely on the 
     specific buggy behaviour. Not just pure API changes like this one, 
     but subtle behavioural changes.

   - API compatibility is very important. As a general rule, we don't
     want to break clients.

   - If we take things to extremes and wait until the next major 
     version to fix *any* issue which *may* have an impact on clients, 
     I don't think anyone will thank us.

   - So, there's a client impact threshold under which we accept the 
     bugfixes without a major version bump.

   - What that threshold is will partly depend on when the next major 
     version will be - e.g. if v3 will be in 5 years time, it wouldn't 
     be sane for us to wait that long to fix issues which have minimal 
     client impact.

   - We certainly do want to get to a point where we can make a 
     commitment to not make changes even this minor, but I don't think 
     the project is there yet.

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

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.

Cheers,
Mark.