Open Stack

> The API layer is a actually quite a very thin layer on top of the
> rest of Nova. Most of the logic in the API code is really just
> checking incoming data, calling the underlying nova logic and then
> massaging what is returned in the correct format. So as soon as you
> change the format the cost of localised changes is pretty much the
> same as duplicating the APIs. In fact I'd argue in many cases its
> more because in terms of code readability its a lot worse and
> techniques like using decorators for jsonschema for input validation
> are a lot harder to implement. And unit and tempest tests still need
> to be duplicated.

Making any change to the backend is double the effort with the two trees
as it would be with one API. I agree that changing/augmenting the format
of a call means some localized "if this then that" code, but that's
minor compared to what it takes to do things on the backend, IMHO.

> I don't understand why this is also not seen as forcing people off
> V2 to V3 which is being given as a reason for not being able to set
> a reasonable deprecation time for V2. This will require major changes
> for people using the V2 API to change how they use it.

Well, deprecating them doesn't require the change. Removing them does. I
think we can probably keep the proxying in a deprecated form for a very
long time, hopefully encouraging new users to "do it right" without
breaking existing users who don't care. Hopefully losing out on the
functionality they miss by not talking directly to Neutron (for example)
will be a good carrot to avoid using the proxy APIs.

> In all the discussions we've (as in the Nova group) had over the API 
> there has been a pretty clear consensus that proxying is quite 
> suboptimal (there are caching issues etc) and the long term goal is
> to remove it from Nova. Why the change now?

This is just MHO, of course. I don't think I've been party to those
conversations. I understand why the proxying is bad, but that's a
different issue from whether we drop it and break our users.

> I strongly disagree here. I think you're overestimating the amount of
> maintenance effort this involves and significantly underestimating
> how much effort and review time a backport is going to take.

Fair enough. I'm going from my experience over the last few cycles of
changing how the API communicates with the backend. This is something
we'll have to continue to evolve over time, and right now it
Sucks Big Time(tm) :)

>> - twice the code
> For starters, It's not twice the code because we don't do things
> like proxying and because we are able to logically separate out
> input validation jsonschema.

You're right, I should have said "twice the code for changes between the
API and the backend".

> Eg just one simple example, but how many people new to the API get
> confused about what they are meant to send when it asks for
> instance_uuid when they've never received one - is at server uuid -
> and if so what's the difference? Do I have to do some sort of
> conversion? Similar issues around project and tenant. And when
> writing code they have to remember for this part of the API they pass
> it as server_uuid, in another instance_uuid, or maybe its just id?
> All of these looked at individually may look like small costs or
> barriers to using the API but they all add up and they end up being
> imposed over a lot of people.

Yup, it's ugly, no doubt. I think that particular situation is probably
(hopefully?) covered up by the various client libraries (and/or docs)
that we have. If not, I think it's probably something we can improve
from an experience perspective on that end. But yeah, I know the public
API docs would still have that ambiguity.

> And how is say removing proxying or making *any* backwards
> incompatible change any different?

It's not. That's why I said "maybe remove it some day" :)

> Well if you never deprecate the only way to do it is to maintain the 
> old API forever (including test). And just take the hit on all that 
> involves.

Sure. Hopefully people that actually deploy and support our API will
chime in here about whether they think that effort is worth not telling
their users to totally rewrite their clients.

If we keep v2 and v3, I think we start in icehouse with a very large
surface, which will increase over time. If we don't, then we start with
v2 and end up with only the delta over time.

> What about the tasks API? We that discussed at the mid cycle summit
> and decided that the alternative backwards compatible way of doing it
> was too ugly and we didn't want to do that. But that's exactly what
> we'd be doing if we implemented them in the v2 API and it would be a 
> feature which ends up looking bolted because of the otherwise 
> significant non backwards compatible API changes we can't do.

If we version the core API and let the client declare the version it
speaks in a header, we could iterate on that interface right? If they're
version <X, return the server object and a task header, if >=X return
the task. We could also let the client declare support in their
accept-type header:

 Accept: application/json;type=task

Which would mean "I can take a JSON task instead of a server". Better
than "if you want a task, rewrite your client against v3" IMHO.

I recognize that tasks were going to be the first big win for v3, but
honestly it feels minor in the context of what we do about v2/v3 long
term, so I don't want to get bogged down in the details of how to do it.

--Dan