Open Stack

On 02/24/2014 05:49 PM, Michael Davies wrote:
> On Tue, Feb 25, 2014 at 8:31 AM, Morgan Fainberg <m at metacloud.com
> <mailto:m at metacloud.com>> 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