On Mon, 24 Feb 2014 11:13:11 -0500 Russell Bryant <rbry...@redhat.com> wrote: > > 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.
So I think its important to point out that we pretty much were "done" before the last minute nova-network unfreezing which became a new requirement for V3 in I-3. And the unfortunate unexpected delay in the tasks API work. If either of those hadn't occurred we could have made up the difference in I-3 - and even then we *could* have made it but for I think reasonable risk purposes in trying to merge a lot of code at the last minute decided to delay. > 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 > looking one. > > 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. So the v2 API and its unit tests are around 43k LOC. And this is even with the v3 API having more tests for the better input validation we do. Just taking this down to burden in terms of LOC (and this may be one of the worst metrics ever). If we proceeded with the v3 API and maintained the V2 API for say 4 cycles, thats and extra burden of 100k LOC compared to just doing the v2 API. But we'd pay that off in just 2 and a bit cycles once the the v2 API is removed because we'd now be maintaining around 25k LOC instead of 43k LOC. > > 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 [1]): > > "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")." Sometimes the problem is that people send extraneous data and they're never told that what they're doing is wrong. But really no harm caused, everything still works. I'm sure there are plenty of examples of this happening. But the bigger issue around input validation being too lax is that people send optional parameters (perhaps with a typo, or perhaps simply in the wrong place) and the API layer quietly ignores them. The users think they've requested some behaviour, the API says "yep, sure!", but it doesn't actually do what they want. We've even seen this sort of thing in our api samples which automatically flows through to our documentation! > 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. I agree, we shouldn't break existing clients - within a major version. That's why we need to make API rev. > > - 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. As discussed above we can't really do a lot on input validation either. And I think the pain of doing the backport is being greatly underestimated. In doing the v3 port we arranged the patches so much of it in terms of review was similar to doing patches to V2 rather than starting from "new code". And I know how hard that was to get it all in during a period when it was easier to review bandwidth. > > > - 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. > > - 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 > > - Fallback for those who really don't want to move after > > deprecation is an API service which translates between V2 and V3 > > requests, but removes the dual API support burden from Nova. > > 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. Well I guess one of the issues I have is that if we continue to backport everything to the V2 API there won't be a compelling reason for existing users to move and it increases our maintenance and development load. But as I've mentioned elsewhere we also have lots of new users coming online (whether they be SDKs or direct users). So what the majority are using within a couple of cycles may look very different. Ultimately how long we keep dual support for is a balance between needs of users and the resources we have to do it. We don't for example support Folsom 2012.2.4 and that's not even a year old! We also don't backport features to previous releases no matter how much our users may want them. So whilst I don't like forcing users off APIs I don't see what's wrong with a clear up front timeline for deprecation. It provides a clear path for users, allows them to plan and they're more likely to move if they know what's coming as opposed to a nebulous "sometime in the future". > 1) Continue as we have been, and plan to release v3 once we have a > compelling enough feature set. So I think we should release in Juno even if its only with tasks and nova-network added. Because this allows new users to start using the API immediately rather than having to code against V2 (with its extra barriers to use) and then take the hit to upgrade later. > 2) Take what we have learned from v3 and apply it to v2. For example: > <snip> > - 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 > implementation). 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 Chris _______________________________________________ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
