Open Stack

On Mon, 24 Feb 2014 17:47:51 -0500
Russell Bryant <rbryant at redhat.com> wrote:
> On 02/24/2014 05:26 PM, Christopher Yeoh wrote:
> >>> - Whilst we have existing users of the API we also have a lot more
> >>>   users in the future. It would be much better to allow them to
> >>> use the API we want to get to as soon as possible, rather than
> >>> trying to evolve the V2 API and forcing them along the transition
> >>> that they could otherwise avoid.
> >>
> >> I'm not sure I understand this.  A key point is that I think any
> >> evolving of the V2 API has to be backwards compatible, so there's
> >> no forcing them along involved.
> > 
> > Well other people have been suggesting we can just deprecate parts
> > (be it proxying or other bits we really don't like) and then make
> > the backwards incompatible change. I think we've already said we'll
> > do it for XML for the V2 API and force them off to JSON.
> 
> Well, marking deprecated is different than removing it.  We have to
> get good data that shows that it's not actually being used before can
> actually remove it.  Marking it deprecated at least signals that we
> don't consider it actively maintained and that it may go away in the
> future.

So the deprecation message in the patch says:

       LOG.warning(_('XML support has been deprecated and will be
         removed in the Juno release.'))

perhaps that should be changed :-)

> I also consider the XML situation a bit different than changing
> specifics of a given API extension, for example.  We're talking about
> potentially removing an entire API vs changing an API while it's in
> use.

That's sort of true, but existing users will have to move to JSON.
Which I think would be a lot more work compared to making someone move
from V2 to V3.

> > Ultimately I think what this would means is punting any significant
> > API improvements several years down the track and effectively
> > throwing away a lot of the worked we've done in the last year on
> > the API
> 
> One of the important questions is how much improvement can we make to
> v2 without breaking backwards compatibility?
> 
> What can we *not* do in a backwards compatible manner?  How much does
> it hurt to give those things up?  How does that compare to the cost
> of dual maintenance?

In terms of user facing changes we can't do a whole lot - because they
are inherently changes in how users communicate with API. And not just
in terms of parameter names, but where and how they access the
functionality (eg url paths change). In the past we've made
mistakes as to where or how functionality should appear, leading to
weird inconsistencies.

So either we can't fix them or in cases where we preserve backwards
compatibility we end up with dual maintenance cost (our test load
still doubles), but often having to be implemented in a way which costs
us more in terms of readability because the code becomes spaghetti.

If it was just a handful changes then I'd agree a major version bump is
not necessary - and we wouldn't have started going down this path over
a year ago. But the user facing improvements are pretty much pervasive
through the API (with the exception of the more recent extensions where
we've got better at enforcing a consistent and sane API style).

Chris