Open Stack

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
<vishvananda at 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 <rbryant at 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 at lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 
Rackspace Australia