Open Stack

> - We want to make backwards incompatible changes to the API
>   and whether we do it in-place with V2 or by releasing V3
>   we'll have some form of dual API support burden.

IMHO, the cost of maintaining both APIs (which are largely duplicated)
for almost any amount of time outweighs the cost of localized changes.

>   - Not making backwards incompatible changes means:
>     - retaining an inconsistent API
>     - not being able to fix numerous input validation issues
>     - have to forever proxy for glance/cinder/neutron with all
>       the problems that entails.

The neutron stickiness aside, I don't see a problem leaving the proxying
in place for the foreseeable future. I think that it's reasonable to
mark them as deprecated, encourage people not to use them, and maybe
even (with a core api version to mark the change) say that they're not
supported anymore.

I also think that breaking our users because we decided to split A into
B and C on the backend kind of sucks. I imagine that continuing to do
that at the API layer (when we're clearly going to keep doing it on the
backend) is going to earn us a bit of a reputation.

>   - Backporting V3 infrastructure changes to V2 would be a
>     considerable amount of programmer/review time

While acknowledging that you (and others) have done that for v3 already,
I have to think that such an effort is much less costly than maintaining
two complete overlapping pieces of API code.

> - The V3 API as-is has:
>   - lower maintenance
>   - is easier to understand and use (consistent).
>   - Much better input validation which is baked-in (json-schema)
>     rather than ad-hoc and incomplete.

In case it's not clear, there is no question that the implementation of
v3 is technically superior in my mind. So, thanks for that :)

IMHO, it is also:

- twice the code
- different enough to be annoying to convert existing clients to use
- not currently different enough to justify the pain

> - Proposed way forward:
>   - Release the V3 API in Juno with nova-network and tasks support
>   - Feature freeze the V2 API when the V3 API is released
>     - Set the timeline for deprecation of V2 so users have a lot
>       of warning

This feels a lot like holding our users hostage in order to get them to
move. We're basically saying "We tweaked a few things, fixed some
spelling errors, and changed some date stamp formats. You will have to
port your client, or no new features for you!" That's obviously a little
hyperbolic, but I think that deployers of APIv2 would probably feel like
that's the story they have to give to their users.

> Firstly I'd like to step back a bit and ask the question whether we
> ever want to fix up the various problems with the V2 API that involve
> backwards incompatible changes. These range from inconsistent naming
> through the urls and data expected and returned, to poor and
> inconsistent input validation and removal of all the proxying Nova
> does to cinder, glance and neutron. I believe the answer to this is
> yes - inconsistencies in the API make it harder to use (eg do I have a
> instance or a server, and a project or a tenant just to name a
> couple) and more error prone and proxying has caused several painful to
> fix issues for us.

I naively think that we could figure out a way to move things forward
without having to completely break older clients. It's clear that other
services (with much larger and more widely-used APIs) are able to do it.

That said, I think the corollary to the above question is: do we ever
want to knowingly break an existing client for either of:

1. arbitrary user-invisible backend changes in implementation or
   service organization
2. purely cosmetic aspects like spelling, naming, etc

IMHO, we should do whatever we can to avoid breaking them except for the
most extreme cases.

--Dan