On 11.12.2012 12:41, Martyn Taylor wrote:
Gentlemen,
We discussed how to model state transitions in the ReST API in the Tech Cabal
and also offline for those who had particularly strong views. One of the
objections brought forward was how to distinguish between clients (end users or
applications) requesting state changes. For example: A developer decides he
wants to terminate his running instances and system services that are used to
notify conductor of when an instance has changed state. For example db-o-matic
wants to tell conductor that the instance has now started.
After some deliberation offline between myself and sseago and without
objections from the Tech Cabal. We decided that the services and the end users
should access different APIs and we should not add complexity into the end user
API in order to support these system services.
This (and the detailed explanation what Scott wrote) makes perfect sense to me.
With this behind us. We then were able to move forward to make a decision on
how to handle requests from a user to transition between states. Like in the
developer example above.
It was agreed that treating the State on an instance as simply an attribute on
the resource (and not an action) was more inline with the ReST principal (Since
adding actions breaks ReST principal of having a unified interface - in our
case the unified interface is defined by HTTP).
So, this now brings us to how we should represent these resources. I think this
is something that can and should be decided on list. I have included below my
opinion on how this should be represented, please add in your own comments.
==
So in my opinion we should model a state machine as an independent resource.
When client wants to change the state of an instance, it looks at the state
machine to figure out what are the possible states I can move to now. The
instance can hold a reference to it's current state and the state machine.
A simple example here: https://gist.github.com/4257951
I wonder whether we really need to model it in such detailed/complex way.
* Modeling states as full resources with IDs assigned feels a bit forced to me.
* Do we want/need to expose the full state machines to clients? Is, and will it
be in future, that current state is the only variable that influences current
possible state transitions? Should the conditions get more complex than this,
then exposing the full state machine correctly as XML might become quite
difficult. I don't think we want to sign up for this unless there is a use case
for it that I fail to imagine now. I kinda hope that exposing the currently
available transitions on each instance should be enough. (CIMI also doesn't
expose more information than currently available transitions, unless I
overlooked it.)
So, if we don't want to represent state changes as links (which doesn't feel
very RESTful to me either), what about going a very simple way like this:
https://gist.github.com/4277759
The updates would be PUT like in your example, but instead of putting a <state>
*link*, we would put a <state> *attribute value*.
Take care,
J.
