<div dir="ltr"><div class="gmail_extra">Yea, looks like no <span style="font-size:14px">consensus at here. Look at the discussion Chris pointed to, the </span>"<span style="font-size:14px">/containers/<ID>/action" sounds a good API for tasks.</span></div><div class="gmail_extra"><br></div><div class="gmail_extra">But we also see<span style="font-size:14px"> the </span><span style="font-size:14px">disadvantage for it. W</span><span style="font-size:14px">hen we want to use URL to identifying an action, we found all the actions into a single API. We faced this problem multiple times:</span></div><div class="gmail_extra"><span style="font-size:14px"><br></span></div><div class="gmail_extra"><span style="font-size:14px">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</span></div><div class="gmail_extra"><span style="font-size:14px">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</span></div><div class="gmail_extra"><span style="font-size:14px">3. Before think about using OpenAPI(swagger) to generate api doc, but the OpenAPI spec didn't support multiple "POST </span><span style="font-size:14px">containers/<ID>/action", that means we need to put all the actions into single entry. That makes the generated doc unreadable.</span></div><div class="gmail_extra"><br></div><div class="gmail_extra">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.</div><div class="gmail_extra"><br></div><div class="gmail_extra">Thanks</div><div class="gmail_extra">Alex</div><div class="gmail_extra"><br><div class="gmail_quote">2016-12-19 19:57 GMT+08:00 Chris Dent <span dir="ltr"><<a href="mailto:cdent+os@anticdent.org" target="_blank">cdent+os@anticdent.org</a>></span>:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><span class="gmail-">On Fri, 16 Dec 2016, Hongbin Lu wrote:<br>
<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
I am from the Zun team and I wanted to consult with you about the API<br>
design. Our team was discussing what is the best API design for<br>
exposing different container operations [1]. There are two proposed<br>
options:<br>
<br>
1. Expose multiple URLs for individual container operation. For example:<br>
</blockquote></span>
[...]<span class="gmail-"><br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
2. Expose a single URL for all operations. For example:<br>
</blockquote></span>
[...]<br>
<br>
How to deal with "actions" is something we've struggled to reach<br>
consensus about in the API-WG. There have been a few proposals over<br>
the years (including some like both of the options you've listed),<br>
but none have been loved by everyone. There's a great deal of<br>
discussion that has happened around this issue and could still<br>
happen. Below is my personal perspective.<br>
<br>
There's a third option you may wish to consider that is perhaps a<br>
bit more resource oriented: use PUT or PATCH to update the state of<br>
the containers representation. Note that the examples should be take<br>
as describing an option, not indicating the right choices for the<br>
terms involved.<br>
<br>
a) GET /containers/<id><br>
<br>
   This gets you a representation including some indicator of state.<br>
<br>
   {...<br>
    "uptime": 542819,<br>
    "state": "running",<br>
    ...<br>
   }<br>
<br>
b) Change that state value to the target and PUT the representation<br>
   back.<br>
<br>
   PUT /containers/<id><br>
<br>
   {...<br>
    "state": "rebooting"<br>
    ...<br>
   }<br>
<br>
   Or, if for some reason you need to save some bytes, you could<br>
   PATCH the state attribute.<br>
<br>
c) If the change takes time and the request is asynchronous, the<br>
   response could be 202 and doing a GET will representing the<br>
   change in progress:<br>
<br>
   GET /containers/<id><br>
<br>
   {...<br>
    "state": "rebooting",<br>
    ...<br>
   }<br>
<br>
   [time passes..]<br>
<br>
   GET /containers/<id><br>
<br>
   {...<br>
    "uptime": 30,<br>
    "state": "running",<br>
    ...<br>
   }<br>
<br>
Like everything this mode has advantages and disadvantages. One<br>
advantage is that we avoid adding URLs. One disadvantage (for some)<br>
is that passing around the full representation is complex and/or<br>
confusing.<br>
<br>
As discussed on the abandoned review[1] referenced from the etherpad<br>
it is important to distinguish between actions which are atomic (at<br>
least from the perspective of the user-agent) and don't need<br>
observation and sequences of tasks which may need observation and<br>
may need to be interrupted and continued.<br>
<br>
The former are changes in resource state, and thus could be<br>
represented as such (as I've described above).<br>
<br>
In the latter, the task is (or tasks are ) the actual resource and<br>
should be the thing that is addressed by URL. That resource should<br>
make reference to the other entities which are being manipulated by<br>
the task.<br>
<br>
>From a user's standpoint stop, start, pause, unpause, reboot etc are<br>
isolated actions that describe a state of the container resource.<br>
<br>
[1] <a href="https://review.openstack.org/#/c/234994/" rel="noreferrer" target="_blank">https://review.openstack.org/#<wbr>/c/234994/</a><span class="gmail-HOEnZb"><font color="#888888"><br>
<br>
-- <br>
Chris Dent                 ¯\_(ツ)_/¯           <a href="https://anticdent.org/" rel="noreferrer" target="_blank">https://anticdent.org/</a><br>
freenode: cdent                                         tw: @anticdent</font></span><br>______________________________<wbr>______________________________<wbr>______________<br>
OpenStack Development Mailing List (not for usage questions)<br>
Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" rel="noreferrer" target="_blank">OpenStack-dev-request@lists.<wbr>openstack.org?subject:<wbr>unsubscribe</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" rel="noreferrer" target="_blank">http://lists.openstack.org/<wbr>cgi-bin/mailman/listinfo/<wbr>openstack-dev</a><br>
<br></blockquote></div><br></div></div>