Open Stack

Yea, looks like no consensus at here. Look at the discussion Chris pointed
to, the "/containers/<ID>/action" sounds a good API for tasks.

But we also see the disadvantage for it. When we want to use URL to
identifying an action, we found all the actions into a single API. We faced
this problem multiple times:

1. In the beginning of thinking about capability discovery, an idea is
about returning a list of URLs if the user have the ability to execute. But
found that all the actions are into single URL
2. Before there is an idea about if the policy rule name is the URL, then
the user can easy to know the mapping between policy rule and API. The same
problem, all the actions into single URL
3. Before think about using OpenAPI(swagger) to generate api doc, but the
OpenAPI spec didn't support multiple "POST containers/<ID>/action", that
means we need to put all the actions into single entry. That makes the
generated doc unreadable.

But yes, that doesn't means we block on this problem. Finally we go to
another direction. So just input something we met before for your
consideration.

Thanks
Alex

2016-12-19 19:57 GMT+08:00 Chris Dent <cdent+os at anticdent.org>:

> On Fri, 16 Dec 2016, Hongbin Lu wrote:
>
> I am from the Zun team and I wanted to consult with you about the API
>> design. Our team was discussing what is the best API design for
>> exposing different container operations [1]. There are two proposed
>> options:
>>
>> 1. Expose multiple URLs for individual container operation. For example:
>>
> [...]
>
>>
>> 2. Expose a single URL for all operations. For example:
>>
> [...]
>
> How to deal with "actions" is something we've struggled to reach
> consensus about in the API-WG. There have been a few proposals over
> the years (including some like both of the options you've listed),
> but none have been loved by everyone. There's a great deal of
> discussion that has happened around this issue and could still
> happen. Below is my personal perspective.
>
> There's a third option you may wish to consider that is perhaps a
> bit more resource oriented: use PUT or PATCH to update the state of
> the containers representation. Note that the examples should be take
> as describing an option, not indicating the right choices for the
> terms involved.
>
> a) GET /containers/<id>
>
>    This gets you a representation including some indicator of state.
>
>    {...
>     "uptime": 542819,
>     "state": "running",
>     ...
>    }
>
> b) Change that state value to the target and PUT the representation
>    back.
>
>    PUT /containers/<id>
>
>    {...
>     "state": "rebooting"
>     ...
>    }
>
>    Or, if for some reason you need to save some bytes, you could
>    PATCH the state attribute.
>
> c) If the change takes time and the request is asynchronous, the
>    response could be 202 and doing a GET will representing the
>    change in progress:
>
>    GET /containers/<id>
>
>    {...
>     "state": "rebooting",
>     ...
>    }
>
>    [time passes..]
>
>    GET /containers/<id>
>
>    {...
>     "uptime": 30,
>     "state": "running",
>     ...
>    }
>
> Like everything this mode has advantages and disadvantages. One
> advantage is that we avoid adding URLs. One disadvantage (for some)
> is that passing around the full representation is complex and/or
> confusing.
>
> As discussed on the abandoned review[1] referenced from the etherpad
> it is important to distinguish between actions which are atomic (at
> least from the perspective of the user-agent) and don't need
> observation and sequences of tasks which may need observation and
> may need to be interrupted and continued.
>
> The former are changes in resource state, and thus could be
> represented as such (as I've described above).
>
> In the latter, the task is (or tasks are ) the actual resource and
> should be the thing that is addressed by URL. That resource should
> make reference to the other entities which are being manipulated by
> the task.
>
> From a user's standpoint stop, start, pause, unpause, reboot etc are
> isolated actions that describe a state of the container resource.
>
> [1] https://review.openstack.org/#/c/234994/
>
> --
> Chris Dent                 ¯\_(ツ)_/¯           https://anticdent.org/
> freenode: cdent                                         tw: @anticdent
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20161220/fa3074e3/attachment.html>