[openstack-dev] [api][zun] Effective URL for resource actions

Qiming Teng tengqim at linux.vnet.ibm.com
Tue Dec 20 03:34:14 UTC 2016

On Tue, Dec 20, 2016 at 10:14:49AM +0800, Alex Xu wrote:
> Yea, looks like no consensus at here. Look at the discussion Chris pointed
> to, the "/containers/<ID>/action" sounds a good API for tasks.

Did you mean "/containers/<ID>/actions" ?
> 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:

Then we should stop identifying actions based on URL. :)
The following URL for representing a 'pause' action is really ugly:


First of all, 'pause' is a verb. I cannot persuade myself that doing a
POST to a verb is a ReST call. And I cannot do a 'GET', 'DELETE' not
due to I'm not an admin ... rather, it is because I cannot explain what
it means by 'deleting a pause'.  
> 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

Neither capability discovery or policy enforcement should be based
solely on URL, IMO. Capabilities should have its own resource
representation if possible. As for policy, it still seems an over
simplification of authorization. There many scenarios where users
want a finer granularity of access control. Even if we want to stick to
the policy.json approach today, we can somehow improve the checking, for

   "containers:action:reboot": "role:owner"

Similarly, auditing and logging can be done in the same way.

> 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.

That is history now. We are moving to the api-ref way of documenting
APIs. Don't tell me there are plans to migrate it back, :D

- Qiming 
> 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>:

More information about the OpenStack-dev mailing list