On Thu, Nov 01, 2012 at 05:59:17PM -0700, Richard Su wrote:
On 11/01/2012 02:32 AM, Jan Provaznik wrote:
>On 10/31/2012 08:36 PM, Richard Su wrote:
>>2. Once created, most deployment fields become read-only. The only two
>>that can be changed are name and state. For state, we will display an
>>available_states field indicating the possible transitions from the
>>current state. Users can PUT the entire xml deployment representation.
>>Changes to read-only fields will be ignored if it is something trivial
>>like a create_at, or will result in an error message if say a change was
>>made to associate with a different pool.
>I'm not sure if deployment/instance actions should be done through update
>action. This was discussed in an older thread here:
>What do you think about creating separate resource(s) for actions?
>Otherwise it looks great.
I remember this discussion. We did consider creating a separate endpoint for
actions, and it is a reasonable approach, but at the end of the day it is
not REST-ful, so we abandoned that idea.
Martyn advocated that we should be moving the resource from one state to
another through PUTs. That's the reason why we're PUT'ing the state even
though the state change is not immediate. The status code we return is 202,
or that the request was accepted and will be processed at a later time.
In this case REST is hiding the complexity of the underlying problem and
e.g. 'run' being a complex task comprising of deploying image and
running it or whatever else has to be done
We do that by pretending that the state is just one attribute of a
But it's really not.
And in the end the consumer of the API has to deal with that anyway. On
his side the API consumer has to poll for state change until it gets to
the desired state or until he finds out that the resource has moved
into some error state. He has to decide how often to poll, how long to
poll, figure out the possible state changes.
So no matter how simple interface you provide he has to take care of the
complexity and has to understand what happens.
All we provide is a hint, that 'this resource is different' by
returning 200 instead of 202.
So instead of providing a decent API for a complex problem we move all
the hard work from the Conductor side to the side of the consumer.
I think Conductor should:
1) provide a way to queue a state change request and
2) together with the request to allow the consumer to specify a callback
(or not if he does not want to) that
3) Conductor would call once the request is resolved
(successfully or not).
If we do not move this way then the API remains simple but the
complexity just moved. This approach does not solve the problem for the
Do I have to say I would not like to consume such API?
Martin Povolny <mpovolny(a)redhat.com>