I think its also pretty unfair on the people who put a lot of work into the v3 API. We're seriously going to delete their code after they put a year into it?
To me OpenStack isn't just the users, its also the development community. I think we do measurable harm to that development community by doing this. We're teaching people that having a blessed plan that was discussed at a summit is not enough to reassure their management chain that they're not wasting time developing something. That worries me a lot. I'm yet to see a third party library (fog, jclouds, etc) express concern about a move to v3 if the deprecation cycle for v2 is nice and long. So why are we so worried? Michael On Tue, Mar 4, 2014 at 8:25 AM, Vishvananda Ishaya <vishvana...@gmail.com> wrote: > This seems like a reasonable and well thought out approach but It feels > like we are removing our ability to innovate. I know we are worried about > maintaining multiple APIs, but I'm still leaning towards putting the v3 > API out and just keeping v2 around for a long time. Yes, its a maintenance > burden, but if we aren't adding a lot of features to v2, I don't know if > it is really THAT bad. > > I'm worried that this is just delaying solving the inconsistency issues to > some future date. > > Vish > > On Mar 3, 2014, at 9:32 AM, Russell Bryant <rbry...@redhat.com> wrote: > >> There has been quite a bit of discussion about the future of the v3 API >> recently. There has been growing support for the idea that we should >> change course and focus on evolving the existing v2 API instead of >> putting out a new major revision. This message is a more complete >> presentation of that proposal that concludes that we can do what we >> really need to do with only the v2 API. >> >> Keeping only the v2 API requires some confidence that we can stick with >> it for years to come. We don't want to be revisiting this any time >> soon. This message addresses a bunch of different questions about how >> things would work if we only had v2. >> >> 1) What about tasks? >> >> In some cases, the proposed integration of tasks is backwards >> compatible. A task ID will be added to a header. The biggest point of >> debate was if and how we would change the response for creating a >> server. For tasks in v2, we would not change the response by default. >> The task ID would just be in a header. However, if and when the client >> starts exposing version support information, we can provide an >> alternative/preferred response based on tasks. >> >> For example: >> >> Accept: application/json;type=task >> >> 2) Versioning extensions >> >> One of the points being addressed in the v3 API was the ability to >> version extensions. In v2, we have historically required new API >> extensions, even for changes that are backwards compatible. We propose >> the following: >> >> - Add a version number to v2 API extensions >> - Allow backwards compatible changes to these API extensions, >> accompanied by a version number increase >> - Add the option to advertise an extension as deprecated, which can be >> used for all those extensions created only to advertise the availability >> of new input parameters >> >> 3) Core versioning >> >> Another pain point in API maintenance has been having to create API >> extensions for every small addition to the core API. We propose that a >> version number be exposed for the core API that exposes the revision of >> the core API in use. With that in place, backwards compatible changes >> such as adding a new property to a resource would be allowed when >> accompanied by a version number increase. >> >> With versioning of the core and API extensions, we will be able to cut >> down significantly on the number of changes that require an API >> extension without sacrificing the ability of a client to discover >> whether the addition is present or not. >> >> 4) API Proxying >> >> We don't see proxying APIs as a problem. It is the cost we pay for >> choosing to split apart projects after they are released. We don't >> think it's fair to break users just because we have chosen to split >> apart the backend implementation. >> >> Further, the APIs that are proxied are frozen while those in the other >> projects are evolving. We believe that as more features are available >> only via the native APIs in Cinder, Glance, and Neutron, users will >> naturally migrate over to the native APIs. >> >> Over time, we can ensure clients are able to query the API without the >> need to proxy by adding new formats or extensions that don't return data >> that needed to be proxied. >> >> 5) Capitalization and Naming Consistency >> >> Some of the changes in the v3 API included changes to capitalization and >> naming for improved consistency. If we stick with v2 only, we will not >> be able to make any of these changes. However, we believe that not >> breaking any existing clients and not having to maintain a second API is >> worth not making these changes, or supporting some indirection to >> achieve this for newer clients if we decide it is important. >> >> 6) Response Code Consistency and Correctness >> >> The v2 API has many places where the response code returned for a given >> operation is not strictly correct. For example a 200 is returned when a >> 202 would be more appropriate. Correcting these issues should be >> considered for improving the future use of the API, however there does >> not seem to be any support for considering this a critical problem right >> now. There are two approaches that can be taken to improve this in v2: >> >> Just fix them. Right now, we return some codes that imply we have dealt >> with a request, when all we have done is queue it for processing (and >> vice versa). In the future, we may change the backend in such a way that >> a return code needs to change to continue to be accurate anyway. If we >> just assume that return codes may change to properly reflect the action >> that was taken, then we can correct existing errors and move on. >> Accept them as wrong but not critically so. With this approach, we can >> strive for correctness in the future without changing behavior of our >> existing APIs. Nobody seems to complain about them right now, so >> changing them seems to be little gain. If the client begins exposing a >> version header (which we need for other things) then we could >> alternately start returning accurate codes for those clients. >> >> The key point here is that we see a way forward with this in the v2 API >> regardless of which path we choose. >> >> 7) Entrypoint based extensions >> >> The v3 effort included improvements to the infrastructure used to >> implement the API, both for proper extensions and modular construction >> of the core API. We definitely want that for v2, and since these are >> just internal implementation details, there is no reason why we can't >> implement these improvements in the v2 API. Note that with the addition >> of versioning of extensions and the core, we should be adding fewer API >> extensions and may be able to collapse some that we already have. >> >> 8) Input Validation >> >> Previously, much of our input validation happened at the database driver >> layer for various reasons. This means that behavior of the API depends >> on such user-invisible things as which RDBM is in use. Thus, our input >> validation is already inconsistent across deployments. Further, the move >> to objects as the communication mechanism between the API and the >> backend means that more input validation is going on than we once had >> anyway, and this is not something we can avoid unless we freeze the >> backend anyway. >> >> Exposing a definition like jsonschema is something that we should do >> anyway, and the process of doing so should allow us to define what was >> previously undefined. Given the variance of the behavior depending on >> the database used on the backend, getting something reasonably strict >> should be roughly equivalent (user-wise) to working against a provider >> that was using something other than MySQL. >> >> 9) v3 ... if not now, when? >> >> Not in the foreseeable future. We don't see it happening unless some >> group of people wanted to rebuild the API from scratch in such a way >> that it doesn't look anything like the current API. The new API would >> have to be different and compelling enough that we'd be willing to >> maintain it along side the current API for several years. >> >> 10) Conclusion and Proposal >> >> The v3 API effort has produced a lot of excellent work. However, the >> majority opinion seems to be that we should avoid the cost of >> maintaining two APIs if at all possible. We should apply what has been >> learned to the existing API where we can and focus on making v2 >> something that we can continue to maintain for years to come. >> >> We recognize and accept that it is a failure of Nova project leadership >> that we did not come to this conclusion much sooner. We hope to have >> learned from the experience to help avoiding a situation like this >> happening again in the future. >> >> Please provide your input on this proposal, even if it is just agreement >> with this as the way forward. >> >> Thanks, >> >> Proposal authors / sponsors: >> >> Russell Bryant >> Dan Smith >> John Garbutt >> Andrew Laski >> >> _______________________________________________ >> OpenStack-dev mailing list >> OpenStack-dev@lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > > > _______________________________________________ > OpenStack-dev mailing list > OpenStack-dev@lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > -- Rackspace Australia _______________________________________________ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
