Thanks for your comment, Miguel.  Your suggestion is indeed very close to the 
RESTful ideal.

However, I have a question for the entire API-WG.  Our (proposed) mission is 
"To improve the developer experience of API users by converging the OpenStack 
API to a consistent and pragmatic RESTful design." [1]  My question is: what is 
the sense of "pragmatic" in this sentence?  I thought it meant that we advise 
the designers of OpenStack APIs to adhere to RESTful design as much as 
possible, but allow them to diverge where appropriate.  The proposed functional 
call to deactivate an image seems to be an appropriate place to deviate from 
the ideal.  Creating a task or action object so that the POST request will 
create a new resource does not seem very pragmatic.  I believe that a necessary 
component of encouraging OpenStack APIs to be consistent is to allow some 



On 2/18/15, 4:49 PM, "Miguel Grinberg" 
<<>> wrote:
Out of all the proposals mentioned in this thread, I think Jay's (d) option is 
what is closer to the REST ideal:

d) POST /images/{image_id}/tasks with payload:
   { "action": "deactivate|activate" }

Even though I don't think this is the perfect solution, I can recognize that at 
least it tries to be RESTful, unlike the other three options suggested in the 
first message.

That said, I'm going to keep insisting that in a REST API state changes are the 
most important thing, and actions are implicitly derived by the server from 
these state changes requested by the client. What you are trying to do is to 
reverse this flow, you want the client to invoke an action, which in turn will 
cause an implicit state change on the server. This isn't wrong in itself, it's 
just not the way you do REST.

Jay's (d) proposal above could be improved by making the task a real resource. 
Sending a POST request to the /tasks address creates a new task resource, which 
gets a URI of its own, returned in the Location header. You can then send a GET 
request to this URI to obtain status info, such as whether the task completed 
or not. And since tasks are now real resources, they should have a documented 
representation as well.


On Wed, Feb 18, 2015 at 1:19 PM, Brian Rosmaita 
<<>> wrote:
On 2/15/15, 2:35 PM, "Jay Pipes" 
<<>> wrote:
>On 02/15/2015 01:13 PM, Brian Rosmaita wrote:
>> On 2/15/15, 10:10 AM, "Jay Pipes" 
>> <<>> wrote:
>>> On 02/15/2015 01:31 AM, Brian Rosmaita wrote:
>>>> This is a follow-up to the discussion at the 12 February API-WG
>>>> meeting [1] concerning "functional" API in Glance [2].  We made
>>>> some progress, but need to close this off so the spec can be
>>>> implemented in Kilo.
>>>> I believe this is where we left off: 1. The general consensus was
>>>> that POST is the correct verb.
>>> Yes, POST is correct (though the resource is wrong).
>>>> 2. Did not agree on what to POST.  Three options are in play: (A)
>>>> POST /images/{image_id}?action=deactivate POST
>>>> /images/{image_id}?action=reactivate
>>>> (B) POST /images/{image_id}/actions with payload describing the
>>>> action, e.g., { "action": "deactivate" } { "action": "reactivate"
>>>> }
>>>> (C) POST /images/{image_id}/actions/deactivate POST
>>>> /images/{image_id}/actions/reactivate
>>> d) POST /images/{image_id}/tasks with payload: { "action":
>>> "deactivate|activate" }
>>> An action isn't created. An action is taken. A task is created. A
>>> task contains instructions on what action to take.
>> The Images API v2 already has tasks (schema available at
>> /v2/schemas/tasks ), which are used for long-running asynchronous
>> operations (right now, image import and image export).  I think we
>> want to keep those distinct from what we're talking about here.
>> Does something really need to be created for this call?  The idea
>> behind the "functional" API was to have a place for things that don't
>> fit neatly into the CRUD-centric paradigm.  Option (C) seems like a
>> good fit for this.
>Why not just use the existing tasks/ interface, then? :) Seems like a
>perfect fit to me.

The existing tasks/ interface is kind of heavyweight.  It provides a
framework for asynchronous operations.  It's really not appropriate for
this purpose.


OpenStack Development Mailing List (not for usage questions)

OpenStack Development Mailing List (not for usage questions)

Reply via email to