Open Stack

On Wed, 26 Feb 2014 11:40:25 +0100
Thierry Carrez <thierry at openstack.org> wrote:
> 
> We may need to differentiate between breaking the API and breaking
> corner-case behavior. In one case you force everyone in the ecosystem
> to adapt (the libraries, the end user code). In the other you only
> (potentially) affect those that were not following the API correctly.
> 
> So there may be a middle ground between "sticking with dirty V2
> forever" and "Go to V3 and accept a long V2 deprecation":
> 
> We could make a V3 that doesn't break the API, only breaks behavior in
> error cases due to its stronger input validation. A V3 that shouldn't
> break code that was following the API, nor require heavy library
> changes. It's still a major API bump because behavior may change and
> some end users will be screwed in the process, but damage is more
> limited, so V2 could go away after a shorter deprecation period.

So honestly I don't think there's much value in a V3 which doesn't break
the API. We really need to fix things like incorrect success return
codes. 

And I think from a user point of view changes which people are saying
the ones we don't need such as naming consistency are the ones which
are the easiest to fix. Its in many cases a simple search and replace
(maybe even with a script). If you have library of some sort in front
of the the rest of your code then it doesn't get far into your app. And
with the really strict input validation with V3 you'll get informed
straight away if you haven't done it all correctly.

However the most valuable changes are the hardest for an app to port
to. For example now receiving a 202 instead of a 200. All of sudden you
realise the call which you thought was synchronous is in fact async.
And that you really should be considering the cases where its slow or
fails. Or the cases where data you used to send is rejected because the
call never used it. You need to think about why you were sending that
extra information, and what you thought the call was doing with it,
that its now obviously not. 

These are things which require semantic changes in your code and are a
lot more costly. But we need to fix them so future users of the
API don't fall into the same traps. So given how much work users of the
API will have to do anyway it seems to make sense to include the minor
stuff at the same time too.

Chris