[rest-practices] Links for actions

[Bill Burke]

David Lutterkort wrote:
> On Fri, 2010-05-07 at 08:45 +0100, Eoghan Glynn wrote:
>> On Thu, 2010-05-06 at 16:46 -0700, David Lutterkort wrote:
>>> One more issue from Deltacloud Core: right now, when a client gets the
>>> details about an instance, we indicate the possible actions on that
>>> instance like this:
>>>
>>>         <actions>
>>>           <link href="/api/instances/inst1/reboot" rel="reboot"/>
>>>           <link href="/api/instances/inst1/stop" rel="stop"/>
>>>           <link href="/api/instances/inst1" rel="destroy"/>
>>>         </actions>
>>>         
>>> The above leaves the client guessing what method to use on the actions,
>>> and contains a little trap: for almost all actions, the method to use is
>>> POST, but for destroy, the client should use the DELETE method, since
>>> they are deleting the server side instance.
>>>
>>> You could argue that this issue is caused by using URL's that do not
>>> represent resources; but then I don't know a better way to indicate
>>> actions.
>>>
>>> My favored way out of this is to add the method the client should use to
>>> the <link/> tag, e.g.
>>>
>>>         <link href="/api/instances/inst1" rel="destroy" method="post"/>
>>
>> Just playing devil's advocate for a moment, but aren't we already
>> implying quite an amount of semantic and structural information in the
>> rel label?
> 
> Yes, that's true .. and yet, the method is what tripped at least one
> client up. The instance actions in the deltacloud API are otherwise very
> uniform: they take no parameters and no request body, and return the
> instance. Adding a method in this specific case allows client code to
> remove one special case.
> 
>> But it would probably be over the top to try to encode all that
>> information explicitly in the link element, e.g.
>>
>> <link rel="attach" href="/storagedomains/XXX/attach"
>> type="application/vnd.redhat.rhevm-api.Action+{xml|json}"
>> errorStatus="400,401,403,409,412" method="POST" />
>>
>> as most of this information can be implicit, or captured in the
>> documentation etc.
> 
> Agreed .. encoding all of that would be overkill. The confusion with
> actions and links really stems from the fact that the URL's mentioned in
> the link are not resources in the usual REST+HTTP sense, i.e., they only
> respond to one specific method, and you can't even do a GET on them.
> 

+1.  There should be no special meaning assigned to error codes.  The 
client should already be aware, through the HTTP specification, what 
error codes it needs to handle and how.  If you need more fine grain 
error messages, then IMO, enclose a media type that tells the client 
what to do.

What I've encountered so far, is that if you rely on the HTTP 
specification, things get simpler and change is easier to introduce. 
The key always is to have the client react to what the server is telling 
it what to do.


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