[openstack-dev] [Nova] Concrete Proposal for Keeping V2 API

Joe Gordon joe.gordon0 at gmail.com
Mon Mar 3 19:37:06 UTC 2014

On Mon, Mar 3, 2014 at 10:49 AM, Russell Bryant <rbryant at redhat.com> wrote:
> On 03/03/2014 01:27 PM, Joe Gordon wrote:
>> On Mon, Mar 3, 2014 at 9:32 AM, Russell Bryant <rbryant at redhat.com> wrote:
>>> 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?
> This is for the case that we want to actually change the response body.
>>>  - 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.
> We have previously required API extensions for adding some things like
> input parameters or attributes on a resource.  The addition of
> versioning for extensions allow us to do this without adding extensions.
>  The point is just that it would be nice if we can mark extensions in
> this category as deprecated and possibly removed since we can express
> these things in terms of versions instead.

That's what I thought just making sure.

>>> 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.
> Right, just shooting for some agreement first.
>>> 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?
> If proxying is required to make an existing API continue to work, we
> should accept it.

Agreed,  but we should accept a new API call that is just a proxy
(unless its EC2 ...)

>>> 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.
> See below ...
>>> 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

Note:  After talking to Russell on IRC, he clarified this is an option
we can consider in the future, not a requirement for v2.

> Again see below ...
>> ++ 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.
> This last sentence is the key here.  Regardless of whether we feel that
> changing return codes is backwards compatible or not, we have a way
> forward in v2.  For the purposes of this conversation, we just have to
> know that we have a way forward in v2.

Overall this sounds great! Thanks for the clarifications, I look
forward to not having to support two APIs simultaneously.

> --
> Russell Bryant
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

More information about the OpenStack-dev mailing list