On 02/24/2014 05:49 PM, Michael Davies wrote: > On Tue, Feb 25, 2014 at 8:31 AM, Morgan Fainberg <[email protected] > <mailto:[email protected]>> wrote: > > On the topic of backwards incompatible changes: > > I strongly believe that breaking current clients that use the APIs > directly is the worst option possible. All the arguments about > needing to know which APIs work based upon which backend drivers are > used are all valid, but making an API incompatible change when we’ve > made the contract that the current API will be stable is a very bad > approach. Breaking current clients isn’t just breaking “novaclient", > it would also break any customers that are developing directly > against the API. In the case of cloud deployments with real-world > production loads on them (and custom development around the APIs) > upgrading between major versions is already difficult to orchestrate > (timing, approvals, etc), if we add in the need to re-work large > swaths of code due to API changes, it will become even more onerous > and perhaps drive deployers to forego the upgrades in lieu of stability. > > If the perception is that we don’t have stable APIs (especially when > we are ostensibly versioning them), driving adoption of OpenStack > becomes significantly more difficult. Difficulty in driving further > adoption would be a big negative to both the project and the community. > > TL;DR, “don’t break the contract”. If we are seriously making > incompatible changes (and we will be regardless of the direction) > the only reasonable option is a new major version > > > I'm absolutely in agreement here - thanks Morgan for raising this. > > Changing the API on consumers means forcing them to re-evaluate their > options: "Should I fix my usage of the API, or is it time to try another > solution? The implementation cost is mostly the same". We can't assume > that API breakages won't lead to customers leaving. It's worth noting > that competing cloud APIs are inconsistent, and frankly awful. But they > don't change because it's all about the commercial interest of retaining > customers and supporting a cornucopia of SDKs. > > Any changes to a versioned API need to be completely backwards > compatible, and we shouldn't assume changes aren't going to break things > - we should test the crap out of them so as to ensure this is the case. > Or put another way, any time we touch a stable API, we need to be > extremely careful. > > If we want new features, if we want to clean up existing interfaces, > it's far better to move to a new API version (even with the maintenance > burden of supporting another API) than try and bolt something on the > side. This includes improving input validation, because we should not > be changing the functionality presented to end-users on a stable API, > even if it's for their own good. What it comes down to is strongly > supporting the consumers of our software. We need to make things easy > for those who support and develop against the APIs.
Let's please avoid too much violent agreement on this. There seems to have been some confusion spurred by Morgan's post. I don't think *anybody* is in favor of non backwards compatible changes to an existing API. The short version of choices discussed in this thread: 1) Continue developing v3 (non backwards compat changes until we call it stable). Maintain v2 and v3 until we reach a point that we can drop v2 (there is debate about when that could be) 2) Focus on v2 only, and figure out ways to add features and evolve it **but only in backwards compatible ways** 3) Some other possible view of a way forward that hasn't been brought up yet, but I'm totally open to ideas -- Russell Bryant _______________________________________________ OpenStack-dev mailing list [email protected] http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
