Open Stack

On Thu, 20 Feb 2014 15:24:22 +0000
John Garbutt <john at johngarbutt.com> wrote:
> 
> > Also micro and extension versioning is not the magic bullet which
> > will get us out of trouble in the future. Especially with the core
> > changes. Because even though versioning allows us to make changes,
> > for similar reasons to not being able to just drop V2 after a
> > couple of cycles we'll still need to keep supporting (and testing)
> > the old behaviour for a significant period of time (we have often
> > quietly ignored this issue in the past).
> 
> I thought the versions were all backwards compatible (for some
> definition of that).

They are, but say you add a backwards compatible change that allows you
to specific a flag that significantly changes the behaviour of the call.
At least from say a tempest point of view you have to test that method
both (with all the various existing possibilities)  with that flag
enabled and with it disabled. So we've doubled the test burden for the
call.

> I did agree with you before now, but I maybe we have "too many" people
> using v2 already. I have been wondering about a half way house...
> 
> So, changes in v3 I would love to keep (highest priority first, as I
> see it):
> * versioning extensions
> * task API
> * internal wiring fix ups (policy, everything is an extension, split
> up extensions)
> * return code fix ups
> * better input validation
> * url (consistency) changes
> * document consistency changes
> 

I think by the time we put these in, we're essentially forcing
people off the old V2 API anyway because we will break existing apps.
We're just being stealthy about it and not bumping the api version.

Why not just instead tell people upfront that they have to move to the
V3 API within X cycles because the V2 API is being removed? 

> Assuming we are happy to retro-fix versions, the question is how much
> do we allow to change between those versions.
> 
> I am good with stuff that would not break a "correct" old API client:
> * allow an API to warn users it is "deprecated"
> * extra attributes may be added in the return document
> * return codes for error cases might get updated
> * the x in 2xx might change for success cases
> * stricter validation of inputs might occur
> 
> Ideally, we only do this once, like at the same time we add in the
> versioning of extensions.
> 
> Having two urls for a single extension seems like quite a low cost
> "fix up", that we can keep in tree. Unit tests should be able to cover
> that, or at least only a small amount of functional tests.
> 
> The clean ups to the format of documents returned, this one is harder:
> * let the client (somehow) choose the new version, maybe a new URL, or
> maybe an Accepts header
> * keep the old version via some "converter" that can be easily unit
> tested in isolation
> 
> The general idea, is to get the fix ups we want, but make it easier to
> maintain, and try to reduce the functional test version, by using the
> knowledge there is so much common code, we don't need a full
> duplication of tests.

Hrm I'm not so sure about that. The API layer is pretty thin and so
essentially there is a lot of common code, but from a tempest point of
view we still fully test against both APIs. I'm not sure I'd feel that
comfortable about not doing so. 

> As far as implementation, I think it would be to make the v3 code
> support v2 and v3, in the process change v3 so thats possible, then
> drop the v2 code.

So I guess my question is adding a v2 backwards compatibility mode to
the v3 code any less burden than just simply keeping the v2 code
around? I don't think it is if it complicates the v2 code too much.

Though I think someone did bring up at the meeting (I'm not sure if it
was you) if it was possible to have a V2<->V3 translation layer. So
perhaps we could have a separate service that just sat in the middle
between a client and nova-api which translated requests and responses
just for V2 API requests to V3 format. And proxied to
neutron/cinder/glance where necessary. That may be one possible solution
to supporting V2 for longer than we'd like whilst at the same time being
able to remove it from Nova. Probably not a trivial thing to implement
but I think it addresses some of the concerns mentioned about keeping
the v2 API around.

This sort of technique might be able to be used to remove the ec2 api
code as well....

Chris