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...@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-requ...@lists.openstack.org?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > >
__________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev