[occi-wg] Nouns and Verbs (was: Syntax of OCCI API)

[Sam Johnston]

Ok so my problem with updating state attributes is that they often are (or
at least should be) immutable. GETting a resource and changing "running" to
"stopped" before PUTting it back just doesn't "feel" right to me, and how do
I know that "stopped" is even a sensible next state unless I track the state
diagram in the client? It would be like retrieving a person and setting
"alive" to "dead" when a "trigger" makes a lot more sense :)

Tim Bray explains it nicely in RESTful
Casuitry<http://www.tbray.org/ongoing/When/200x/2009/03/20/Rest-Casuistry>
:

> The next argument is about all the other “controller” functions. Deploying
> a model, starting and stopping and rebooting a machine, attaching networks.
> The argument is that it’d be more RESTful to have some state fields in the
> appropriate representations, and just update those fields to the desired new
> state values.
>
> Now, doing this, once again, would require almost no code changes.
>
> But I don’t buy it, and here’s why. If I want to update some fields in an
> existing resource, I’m inclined to think about PUT. But that doesn’t work
> because it’s supposed to be idempotent, and rebooting a server sure isn’t.
> Well, OK, do it with POST I guess; no biggie.
>
> But you’re not really changing a state, you’re requesting a specific set of
> actions to happen, as a result of which the state may or may not attain the
> desired value. In fact, when you hit the deploy switch, the state changes
> to deploying and then after some unpredictable amount of time to deployed.
> And the reboot operation is the classic case of a box with a big red
> switch on the side; the problem is how to push the switch.
>
> So, the more I think of it, the more I think that these resources are like
> buttons, with only one defined operation: push. People have been whining
> about “write-only resources” but I don’t have a problem with that because it
> seems accurate. The reboot and halt buttons don’t really have any state,
> so you shouldn’t expect anything useful from a GET.
>
Tim talks about both [unpredictable amounts of] time and idempotency (that
is, repetitions of the action have no further effect on outcome).

I like this approach a lot and it's one of a number of things that we've
learnt from the Sun Cloud APIs.

Sam

On Fri, Apr 17, 2009 at 1:34 PM, Edmonds, AndrewX <andrewx.edmonds at intel.com
> wrote:

> +1 +$0.00001 :-)
>
> Excellent principles;
> "simplify to actual actions on the server resource itself" - yes
>
> " define a range of nouns for common resources, a limited set of verbs for
> actions and a range of attributes to describe common characteristics." Yes,
> perfect.
>
> And a resounding yes to the aspect of "attribute changes that are
> transitory at this moment in time"
>
>
> -----Original Message-----
> From: occi-wg-bounces at ogf.org [mailto:occi-wg-bounces at ogf.org] On Behalf
> Of Simon Wardley
> Sent: 17 April 2009 12:18
> To: Sam Johnston
> Cc: occi-wg at ogf.org
> Subject: Re: [occi-wg] Nouns and Verbs (was: Syntax of OCCI API)
>
> Hi Sam,
>
> My $0.00001 worth and sorry if these questions / observations are dumb.
>
> > {noun{verb{attribute}}} vector
>
> +1 for this.
>
> > I specifically don't like the idea of differentiating between physical
> > and virtual resources
>
> I couldn't agree more with this statement.
>
> The language used should be consistent regardless of the mechanism of
> implementation of a resource. If I'm using a remote infrastructure
> service, there should be no reason for me to care how that
> infrastructure is delivered other than that resource has certain
> attributes (e.g. persistence etc).
>
> In the format of {noun{verb{attribute}}}
>
> The approach of {resource_provider/my_id/servers {create{attributes}}
> should simply create a server with the attributes given.
>
> > Ok so nouns and verbs (ignoring CRUD which is common anyway):
> > storage:
> >  - snapshot?
> >  - backup?
>
> My really dumb questions are:-
>
> 1. In the format of {noun{verb{attribute}}}  shouldn't back-up and
> snapshot simply be:-
>
> {resource_provider/my_id/storage/my_backup_store {update
> {other_resource_provider/my_id/storage/my_store}}
>
> 2. When it comes to stopping and starting servers, aren't these simply
> attributes of the server. Whether its active state is on or off seems
> little different from other attributes of that specific resource.
>
> The only reason why we describe a process of stopping or starting a
> server at this moment in time is because of hardware constraints, but
> then I'm an old git and remember the 5 minutes or so that I use to have
> to wait to "park" my winchester drives before switching off the power.
>
> I fully expect future SSD to have near instantaneous changes in state.
>
> So my question is, are we describing verbs for attribute changes that
> are transitory at this moment in time?
>
> Should we not simplify to actual actions on the server resource itself,
> i.e. :-
>
> creating a server
> {resource_provider/my_id/servers {create{attributes}}
>
> deleting a server
> {resource_provider/my_id/servers/some_server {delete{...}}
>
> reading characteristics of a server
> {resource_provider/my_id/servers/some_server {read{some attribute}}
>
> cloning a server
> {resource_provider/my_id/servers/some_server
> {update{resource_provider/my_id/servers/some_other_server}}
>
> stopping / starting a server
> {resource_provider/my_id/servers/some_server {update{state attribute}}
>
> list all servers (or servers with a specific attribute such as running)
> {resource_provider/my_id/servers {read{{...}}
>
> The same seems to be generally true with other resources (i.e. storage,
> networks, servers etc).
>
> Just my thoughts, I'd define a range of nouns for common resources, a
> limited set of verbs for actions and a range of attributes to describe
> common characteristics.
>
> Feel free to ignore me if I've missed the point.
>
> --
> Simon Wardley
> Software Services Manager,
> Canonical Ltd.
> TEL: +44 (0)207 630 2451
> MOB : +44 (0)7972 911 449
> TWITTER: http://www.twitter.com/swardley/
>
> _______________________________________________
> occi-wg mailing list
> occi-wg at ogf.org
> http://www.ogf.org/mailman/listinfo/occi-wg
> -------------------------------------------------------------
> Intel Ireland Limited (Branch)
> Collinstown Industrial Park, Leixlip, County Kildare, Ireland
> Registered Number: E902934
>
> This e-mail and any attachments may contain confidential material for
> the sole use of the intended recipient(s). Any review or distribution
> by others is strictly prohibited. If you are not the intended
> recipient, please contact the sender and delete all copies.
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.ogf.org/pipermail/occi-wg/attachments/20090417/558f8927/attachment.html