[openstack-dev] [Glance][TC] Glance Functional API and Cross-project API Consistency

Christopher Yeoh cbkyeoh at gmail.com
Wed Jun 11 02:33:45 UTC 2014

On Wed, Jun 11, 2014 at 8:45 AM, Jay Pipes <jaypipes at gmail.com> wrote:

> On Wed, Jun 4, 2014 at 11:54 AM, Sean Dague <sean at dague.net> wrote:
>> On 05/30/2014 02:22 PM, Hemanth Makkapati wrote:
>> > Hello All,
>> > I'm writing to notify you of the approach the Glance community has
>> > decided to take for doing functional API.  Also, I'm writing to solicit
>> > your feedback on this approach in the light of cross-project API
>> > consistency.
>> >
>> > At the Atlanta Summit, the Glance team has discussed introducing
>> > functional API in Glance so as to be able to expose operations/actions
>> > that do not naturally fit into the CRUD-style. A few approaches are
>> > proposed and discussed here
>> > <
>> https://etherpad.openstack.org/p/glance-adding-functional-operations-to-api
>> >.
>> > We have all converged on the approach to include 'action' and action
>> > type in the URL. For instance, 'POST
>> > /images/{image_id}/actions/{action_type}'.
>> >
>> > However, this is different from the way Nova does actions. Nova includes
>> > action type in the payload. For instance, 'POST
>> > /servers/{server_id}/action {"type": "<action_type>", ...}'. At this
>> > point, we hit a cross-project API consistency issue mentioned here
>> > <
>> https://etherpad.openstack.org/p/juno-cross-project-consistency-across-rest-apis
>> >
>> > (under the heading 'How to act on resource - cloud perform on
>> > resources'). Though we are differing from the way Nova does actions and
>> > hence another source of cross-project API inconsistency , we have a few
>> > reasons to believe that Glance's way is helpful in certain ways.
>> >
>> > The reasons are as following:
>> > 1. Discoverability of operations.  It'll be easier to expose permitted
>> > actions through schemas a json home document living at
>> > /images/{image_id}/actions/.
>> > 2. More conducive for rate-limiting. It'll be easier to rate-limit
>> > actions in different ways if the action type is available in the URL.
>> > 3. Makes more sense for functional actions that don't require a request
>> > body (e.g., image deactivation).
>> >
>> > At this point we are curious to see if the API conventions group
>> > believes this is a valid and reasonable approach.
>> > Any feedback is much appreciated. Thank you!
>> Honestly, I like POST /images/{image_id}/actions/{action_type} much
>> better than ACTION being embedded in the body (the way nova currently
>> does it), for the simple reason of reading request logs:
> I agree that not including the action type in the POST body is much nicer
> and easier to read in logs, etc.
> That said, I prefer to have resources actually be things that the software
> creates. An action isn't created. It is performed.
So that depends a bit on whether the action can be performed immediately or
not. Sometimes presumably it can?

I would prefer to replace the term "action(s)" with the term "task(s)", as
> is proposed for Nova [1].
I agree It'd probably be worth other projects looking at the proposed tasks
API for Nova for long running tasks. Better that the infra
for it be put in now and return task handles than have to try to retrofit
something later on.

As for the earlier question about whether Nova should try to follow this
proposal. IMO I think Nova should, but its something we'd converge to
over the long term (presumably using a microversion bump).


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140611/d4791364/attachment.html>

More information about the OpenStack-dev mailing list