On 02/24/2014 01:50 AM, Christopher Yeoh wrote:
There has recently been some speculation around the V3 API and whether
we should go forward with it or instead backport many of the changes
to the V2 API. I believe that the core of the concern is the extra
maintenance and test burden that supporting two APIs means and the
length of time before we are able to deprecate the V2 API and return
to maintaining only one (well two including EC2) API again.
Yes, this is a major concern. It has taken an enormous amount of work
to get to where we are, and v3 isn't done. It's a good time to
re-evaluate whether we are on the right path.
The more I think about it, the more I think that our absolute top goal
should be to maintain a stable API for as long as we can reasonably do
so. I believe that's what is best for our users. I think if you gave
people a choice, they would prefer an inconsistent API that works for
years over dealing with non-backwards compatible jumps to get a nicer
The v3 API and its unit tests are roughly 25k lines of code. This also
doesn't include the changes necessary in novaclient or tempest. That's
just our code. It explodes out from there into every SDK, and then
end user apps. This should not be taken lightly.
This email is rather long so here's the TL;DR version:
- 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.
- Not making backwards incompatible changes means:
- retaining an inconsistent API
I actually think this isn't so bad, as discussed above.
- not being able to fix numerous input validation issues
I'm not convinced, actually. Surely we can do a lot of cleanup here.
Perhaps you have some examples of what we couldn't do in the existing API?
If it's a case of wanting to be more strict, some would argue that the
current behavior isn't so bad (see robustness principle ):
"Be conservative in what you do, be liberal in what you accept from
others (often reworded as "Be conservative in what you send, be
liberal in what you accept")."
There's a decent counter argument to this, too. However, I still fall
back on it being best to just not break existing clients above all else.
- have to forever proxy for glance/cinder/neutron with all
the problems that entails.
I don't think I'm as bothered by the proxying as others are. Perhaps
it's not architecturally pretty, but it's worth it to maintain
compatibility for our users.
- Backporting V3 infrastructure changes to V2 would be a
considerable amount of programmer/review time
Agreed, but so is the ongoing maintenance and development of v3.
- 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.
So here's the rub ... with the exception of the consistency bits, none
of this is visible to users, which makes me think we should be able to
do all of this on v2.
- 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.
One of my biggest principles with a new API is that we should not have
to force a migration with a strict timeline like this. If we haven't
built something compelling enough to get people to want to migrate as
soon as they are able, then we haven't done our job. Deprecation of the
old thing should only be done when we feel it's no longer wanted or used
by the vast majority. I just don't see that happening any time soon.
We have a couple of ways forward right now.
1) Continue as we have been, and plan to release v3 once we have a
compelling enough feature set.
2) Take what we have learned from v3 and apply it to v2. For example:
The plugin infrastructure is an internal implementation detail that
can be done with the existing API.
extension versioning is a concept we can add to v2
we've also been discussing the concept of a core minor version, to
reflect updates to the core that are backwards compatible. This
seems doable in v2.
revisit a new major API when we get to the point of wanting to
effectively do a re-write, where we are majorly re-thinking the
way our API is designed (from an external perspective, not internal