Bill,

Ironically Adrian wrote this post after being prompted by myself and Andy Edmonds from the OCCI-WG following criticism of exactly this approach. I definitely think links are a great way of satisfying the hypertext constraint (formerly known as HATEOAS) but I'm intrigued by what specific problems he has with this approach - e.g. "what could possibly go wrong"?

In many (most?) cases the "actions" are not parametrised in which case the entity-body is empty, but the alternative, doing an empty POST to a parametrised (GET-style) URL, feels [very] wrong. While URLs should be considered opaque, I'm ok with using either semicolons or path segments ('/') to delineate actions:

http://example.com/vm01;start

but the following "feels funky":

http://example.com/disk01;resize=20000

I much prefer:

POST http://example.com/disk01;resize
size=20000

So what we are currently doing for "actions" is a post/redirect/get pattern which I feel is quite elegant in that it allows us to handle more challenging realities such as asynchronous responses (e.g. returning HTTP 201 Accepted with a Location: header which can be monitored ala pubsubhubbub or polled).

Adrian was talking about servers returning 409 Conflict but I don't have a problem with that either - if so the client knows it can try again later and doing anything else (like saving and replaying the request on the server side) doesn't seem right to me either as it's a form of server-side state.

Anyway it's good to see this all starting to coalesce - just need to sort out the nitty gritty details.

Sam

On Thu, Oct 15, 2009 at 1:43 AM, Bill Burke <bburke@redhat.com> wrote:

Well, the more restful way of doing it would be:

GET of /objects/robot/3333 returns:

{"robot" :
   {"name" : "Mr. Roboto",
    "links" : [ {"rel" : "kill", "href" : "http://.../objects/robot/3333/kill", "type" : "application/x-form-urlencoded}]
   }
}

So, the idea is you get the representation of the robot, and the links define what relationships are to the robot.  One of the relationships is "kill".  You follow the link by posting to it:

POST /objects/robot/333/kill

death=slow

GET of /objects/robot/333/kill might return:

"This robot died a slow death"

The thing is here that the URL patterns are irrelevant, the URLs are opaque, you navigate to them by linking.


Adrian Cole wrote:
sorry.. the rendering is bad in firefox.

Here's the matrix example:

POST http://localhost:8080/objects/robot/action/kill;death=slow HTTP/1.1

Here's the entity example (objects renamed from a real cloud api):

POST http://localhost:8080/objects/robot/action HTTP/1.1
Content-Length: 25

{"kill":{"death":"slow"}}


This is probably more high-level, but if it is rest to address resources as /path/to and operate them with POST, DELETE, etc, it may come naturally for some who are FSMs to offer state transition commands.  In this case, simple command patterns come in handy and are currently in use in compute clouds, for example.

I hope this background helps.  If the topic doesn't fit the list, let me know.
Cheers,
-Adrian


On Wed, Oct 14, 2009 at 2:55 PM, Bill Burke <bburke@redhat.com <mailto:bburke@redhat.com>> wrote:


   REST is not an RPC model...Or maybe I'm misinterpreting you.  Also,
   the code examples in your blog are cut off.


   Adrian Cole wrote:

       Hi, all.

       I'd like your opinion on modeling ReST commands on the server
       side.  I've placed a suggestion for thought on my blog [1].
        Please let me know what you think.  The basic idea is to prefer
       not using entities on commands as it makes retry logic easier.
        In such case, we can use Matrix Params instead.

       Cheers.
       -Adrian
       founder jclouds

       [1]
       http://anyweight.blogspot.com/2009/10/rest-be-nice-no-entities-please.html

       http://www.reddit.com/r/programming/comments/9u2ic/rest_be_nice_no_entities_please/
       http://digg.com/programming/ReST_be_nice_no_entities_please


   --    Bill Burke
   JBoss, a division of Red Hat
   http://bill.burkecentral.com



--
Bill Burke
JBoss, a division of Red Hat
http://bill.burkecentral.com