Open Stack

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