Open Stack

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.

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

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

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.

-- 
Russell Bryant