<html><body>
<p><font size="2" face="sans-serif">+1 to the reasoning and position taken. Nicely put. <br>
</font><font size="2" face="sans-serif"><br>
</font><font size="2" face="sans-serif">Chris<br>
</font><font size="2" face="sans-serif"><br>
</font><font size="2" face="sans-serif">Sent from my iPad<br>
</font><font size="2" face="sans-serif"><br>
</font><font size="2" face="sans-serif">On Jul 25, 2012, at 12:51 PM, "Mark McLoughlin" <markmc@redhat.com> wrote:<br>
</font><font size="2" face="sans-serif"><br>
</font><font size="2" face="sans-serif">> Hey,<br>
</font><font size="2" face="sans-serif">> <br>
</font><font size="2" face="sans-serif">> Trying to get away from this specific issue for a minute ... some<br>
</font><font size="2" face="sans-serif">> points:<br>
</font><font size="2" face="sans-serif">> <br>
</font><font size="2" face="sans-serif">> - We fix bugs all the time that may affect clients which rely on the<br>
</font><font size="2" face="sans-serif">> specific buggy behaviour. Not just pure API changes like this one,<br>
</font><font size="2" face="sans-serif">> but subtle behavioural changes.<br>
</font><font size="2" face="sans-serif">> <br>
</font><font size="2" face="sans-serif">> - API compatibility is very important. As a general rule, we don't<br>
</font><font size="2" face="sans-serif">> want to break clients.<br>
</font><font size="2" face="sans-serif">> <br>
</font><font size="2" face="sans-serif">> - If we take things to extremes and wait until the next major<br>
</font><font size="2" face="sans-serif">> version to fix *any* issue which *may* have an impact on clients,<br>
</font><font size="2" face="sans-serif">> I don't think anyone will thank us.<br>
</font><font size="2" face="sans-serif">> <br>
</font><font size="2" face="sans-serif">> - So, there's a client impact threshold under which we accept the<br>
</font><font size="2" face="sans-serif">> bugfixes without a major version bump.<br>
</font><font size="2" face="sans-serif">> <br>
</font><font size="2" face="sans-serif">> - What that threshold is will partly depend on when the next major<br>
</font><font size="2" face="sans-serif">> version will be - e.g. if v3 will be in 5 years time, it wouldn't<br>
</font><font size="2" face="sans-serif">> be sane for us to wait that long to fix issues which have minimal<br>
</font><font size="2" face="sans-serif">> client impact.<br>
</font><font size="2" face="sans-serif">> <br>
</font><font size="2" face="sans-serif">> - We certainly do want to get to a point where we can make a<br>
</font><font size="2" face="sans-serif">> commitment to not make changes even this minor, but I don't think<br>
</font><font size="2" face="sans-serif">> the project is there yet.<br>
</font><font size="2" face="sans-serif">> <br>
</font><font size="2" face="sans-serif">> - Our API documentation doesn't cover every aspect of the API which<br>
</font><font size="2" face="sans-serif">> clients may come to rely on. We also don't really document what<br>
</font><font size="2" face="sans-serif">> clients should avoid relying on (e.g. URL structure, specific<br>
</font><font size="2" face="sans-serif">> response codes etc.) so we can't always rely on the documentation<br>
</font><font size="2" face="sans-serif">> to tell us whether an API fix is acceptable.<br>
</font><font size="2" face="sans-serif">> <br>
</font><font size="2" face="sans-serif">> - I hate to think of us rejecting API fixes with "this needs to wait<br>
</font><font size="2" face="sans-serif">> until v3" and then, when v3 comes around, we don't actually get<br>
</font><font size="2" face="sans-serif">> around to fixing those issues. We need some way of channelling<br>
</font><font size="2" face="sans-serif">> people's desire to fix the API, even if that's just helping to<br>
</font><font size="2" face="sans-serif">> document what needs fixing in v3.<br>
</font><font size="2" face="sans-serif">> <br>
</font><font size="2" face="sans-serif">> So, thinking about this specific issue:<br>
</font><font size="2" face="sans-serif">> <br>
</font><font size="2" face="sans-serif">> - "201 Created" is clearly the right behaviour and is what we do<br>
</font><font size="2" face="sans-serif">> elsewhere in the API. Unfortunately, we don't document this so we<br>
</font><font size="2" face="sans-serif">> can't just say "see, we're just making it compliant with the spec".<br>
</font><font size="2" face="sans-serif">> <br>
</font><font size="2" face="sans-serif">> - Some clients may be relying on "200 OK" and they may be affected<br>
</font><font size="2" face="sans-serif">> by this change. However, more sensible clients would just accept<br>
</font><font size="2" face="sans-serif">> any 2xx code as success. In terms of impact that I expect API<br>
</font><font size="2" face="sans-serif">> clients may see between Essex and Folsom, my guess is this is<br>
</font><font size="2" face="sans-serif">> pretty minor.<br>
</font><font size="2" face="sans-serif">> <br>
</font><font size="2" face="sans-serif">> - I don't know of any plans for v3. I also don't know that we have<br>
</font><font size="2" face="sans-serif">> any way to channel this effort into preparing for v3.<br>
</font><font size="2" face="sans-serif">> <br>
</font><font size="2" face="sans-serif">> No-one reading this should interpret it as a lack of understanding of<br>
</font><font size="2" face="sans-serif">> the importance of API compatibility. There is a spectrum of API compat<br>
</font><font size="2" face="sans-serif">> strictness. Where we fall on the spectrum at this point of the project's<br>
</font><font size="2" face="sans-serif">> life isn't a trivial question. We don't want to be at either of the<br>
</font><font size="2" face="sans-serif">> extreme ends of the spectrum (e.g. the rules Sun used to apply to<br>
</font><font size="2" face="sans-serif">> Solaris changes vs Ruby libraries which change API every day of the<br>
</font><font size="2" face="sans-serif">> week), so please don't try and make out this is a black-and-white thing.<br>
</font><font size="2" face="sans-serif">> <br>
</font><font size="2" face="sans-serif">> Cheers,<br>
</font><font size="2" face="sans-serif">> Mark.<br>
</font><font size="2" face="sans-serif">> <br>
</font><font size="2" face="sans-serif">> <br>
</font><font size="2" face="sans-serif">> _______________________________________________<br>
</font><font size="2" face="sans-serif">> OpenStack-dev mailing list<br>
</font><font size="2" face="sans-serif">> OpenStack-dev@lists.openstack.org<br>
</font><font size="2" face="sans-serif">> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
</font><font size="2" face="sans-serif">> <br>
</font></body></html>