← Back to team overview

openstack team mailing list archive

Proposal to defer existing OS API v1.1 to Diablo, for greater stability in Cactus


I have been doing some work on getting XML support in our APIs in better
shape in the OS API.  However we feel about XML, the big benefit is that it
gives us really strict validation for free.  I am only at the point of
adding namespace declarations, but this has already uncovered a lot of
issues where our current output isn't entirely to spec (as defined by the
CloudServers v1.0 API and the OpenStack v1.1 API)  This applies to our JSON
output as much as it applies to our XML output.

The Titan team have been doing great work, but I think we've handed them a
death march if they're to complete all this work for both v1.0 and v1.1 in
time.  I'd rather they were able to focus on one API, or even have time for
the many other bugs we still have :-)

The big problem with the v1.1 spec as I see it, is that it includes a lot of
changes which I don't believe are strictly necessary (hopefully simply
because I don't understand them).  For example:

   - The atom links collection (images, flavors, servers)
   - Random changes (e.g. limits, addresses), where e.g. attributes move to
   their parent elements.  Probably more correct, but is it really worth the
   implementation cost on our side or on the caller's side?
   - Changing from a numeric ID to a URI (e.g. on images), but then not
   really using the URI (or even having two URIs)
   - And these are just the 'known knowns' :-)

To reiterate - this is in no way a criticism of the Titan team.  They've got
many of these already implemented, and with luck and great effort they could
deliver all of them.  If they're willing and able to do that, great.

However, we need to have an API that works 100% in Cactus, and I don't think
we should demand that the Titan team death-march to deliver _two_ APIs.  I
also think if we want to get good client support, we should minimize the
number of changes we require API callers to make, particularly if we don't
have a big carrot to offer them in return.

I would like to propose a fallback scenario for Cactus release management
purposes, which would free up Titan resources and get us a better, more
stable API with greater client support:

   - We defer any non-essential changes in the V1.1 API to post-Cactus.
   - We can then discuss these thoroughly at the design summit (I do not
   believe we had a design summit discussion on these API changes, for timing
   - We make the V1.1 API a minimal extension to V1.0, to support the Cactus
   features we're going to ship.  For example, Brian Waldon pointed out that we
   would need a new element for the changePassword action, and for extensions
   - These minimal differences would be driven by the people that need them
   (primarily the Titan team)  I am confident they're not going to be
   introducing things that are not strictly necessary at this stage of the game
   - We may have to postpone extensions that inject additional content into
   existing elements, and stick to extensions that extend the URI space, so
   that the XML schema for V1.1 is minimal.  Extension of existing elements
   probably warrants a Design Summit discussion anyway.  We do not yet have any
   (non-test) extensions that inject content.
   - We would rename the current V1.1 API to V1.2 or V2.0 - we are just
   deferring it to Diablo, not abandoning it.
   - We could still ship the renamed API as "experimental", even in Cactus
   - The goal is to focus resources on one API that will then work 100%.
   - Yes, it's still sort of going to be two APIs, but if we're really lucky
   we might get away with almost no 'switching' code.  For example, if we _add_
   a URI or an action, a V1.0 client will never discover it.
   - In particular, we want to avoid the output format changing between
   versions wherever we can.
   - I hope by virtue of this approach that Cactus will be 100% compatible
   with existing v1.0 (CloudServers) clients
   - I hope also that V1.0 clients can just switch to use the V1.1 endpoint
   when they're ready, and need make code changes only for things which have
   actually changed.

I believe this is entirely in line with our goals for Cactus.  I am less
confident that the current V1.1 API is in line with our Cactus goals.

Thoughts?  Anyone from the Titan team want to comment on how they feel about
the timetable for delivering the APIs in Cactus?  ttx?


Follow ups