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

Brian Rosmaita brian.rosmaita at RACKSPACE.COM
Wed Jun 11 04:25:38 UTC 2014

> That said, I prefer to have resources actually be things that the software creates. An action
> isn't created. It is performed.
> I would prefer to replace the term "action(s)" with the term "task(s)", as is proposed for Nova [1].

Glance already uses "tasks" in the v2 URL for creating resources that represent long-running asynchronous processes (import, export, cloning), so that terminology is already taken.  (The documentation is lagging a bit behind the code on tasks, though.)

The aim here is to introduce something that doesn't fit cleanly into a CRUD-centric view.  For example, a cloud provider may need to put an imported (or otherwise problematic) image into "deactivated" status while the image is being investigated for some malicious stuff built into it [2].  Image status, however, is never set directly by users or admins; image status transitions are handled entirely by Glance.  (You don't delete an image by updating its status to be 'deleted'; rather, its status becomes 'deleted' as a result of a DELETE request).  Using an Images v2 PATCH call in this context would be misleading because we're not modifying the image's status--we can't.  We're asking Glance to take an action with respect to an image, the result of which will be that the image will be deactivated (or reactivated), and Glance will modify the image's status accordingly.


[1] https://review.openstack.org/#/c/86938/
[2] https://wiki.openstack.org/wiki/Glance-deactivate-image
From: Jay Pipes [jaypipes at gmail.com]
Sent: Tuesday, June 10, 2014 7:15 PM
To: OpenStack Development Mailing List (not for usage questions)
Subject: Re: [openstack-dev] [Glance][TC] Glance Functional API and Cross-project API Consistency

On Wed, Jun 4, 2014 at 11:54 AM, Sean Dague <sean at dague.net<mailto: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.

I would prefer to replace the term "action(s)" with the term "task(s)", as is proposed for Nova [1].

Then, I'd be happy as a pig in, well, you know.


[1] https://review.openstack.org/#/c/86938/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140611/f039f089/attachment.html>

More information about the OpenStack-dev mailing list