On Mon, Mar 3, 2014 at 10:49 AM, Russell Bryant <rbry...@redhat.com> wrote: > On 03/03/2014 01:27 PM, Joe Gordon wrote: >> On Mon, Mar 3, 2014 at 9:32 AM, Russell Bryant <rbry...@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@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