Open Stack

On 3/3/2014 12:27 PM, Joe Gordon wrote:
> On Mon, 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
>
> The current https://wiki.openstack.org/wiki/APIChangeGuidelines says
> its OK add a new response header, so do we even need this?
>
>
>>
>> 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
>
> Can you elaborate on this last point.
>
>>
>> 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.
>
> ++, looks like we may need to update
> https://wiki.openstack.org/wiki/APIChangeGuidelines and make this
> clear to downstream users.
>
>>
>> 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.
>
> Can you expand on what this last paragraph means?
>
> While I agree in not breaking users. I assume this means we won't
> accept any new proxy APIs?
>
>>
>> 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.
>
> Changing return codes always scares me, we risk breaking code that
> says if '==200.' Although having versioned backwards compatable APIs
> makes this a little better.
>
>> 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.
>
> Wait what? client needs version headers? Can you expand
>
> ++ to accepting them as wrong and moving on.
>>
>> 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.
>
> As long as we can bump the API version (backwards compatible bump of
> course) then ++.
>
>>
>> 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.
>>
>
> Hooray for deleting code

Personally I'd like to see this bake for a bit, not turn into a huge 
thread like the other one already is, but let things settle for a bit 
between now and the Juno summit and then let people talk about this in 
person before there are any proposals to completing deleting all of the 
V3 code.  Unfortunately it didn't come up before the meetup in Utah, but 
if it can sit for a bit I think it'd be helpful to hash it out in Atlanta.

>
>> 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
>

-- 

Thanks,

Matt Riedemann