Open Stack

On Mon, Dec 19, 2016 at 11:57:26AM +0000, Chris Dent wrote:
> 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:

My gut feeling is that most "actions" we are initiating fall into the
asynchronous group. For example, we are not modeling a GET request on
/containers/<ID> as an action.
 
>    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.

Another disadvantage is about access control (aka. policy). We will have
to check who is authorized to change which field to what value. Going
further down this direction we may have, for example:

   PUT/PATCH /containers/<ID>/state

But we still can see a lot limitations in this approach.
 
> 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.

Having a single URI /containers/<ID>/actions to model this seems a
better option in my opinion. These tasks are the things we are
authorizing, validating, performing, verifying, auditing... A
single task/action may change more than one states. Abstracting these
operations into state changes doesn't look the right to do.

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