[rest-practices] Links for actions

[Eoghan Glynn]

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?

We're saying the action maps to some real-world operation, that we
expect an entity body of a certain type, that we may return a response
of another type, or indicate a error condition with certain specific
status codes and maybe even a fault entity-body with further detail.

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.

If we were to encode anything explicitly, I'm thinking the expected
fine-grained media type must be more useful information, as the verb is
usually POST and in any case if the client gets it wrong we can prod it
into recovering gracefully via a 405 "Method Not Allowed" response with
an "Allow: DELETE" header for example.

Cheers,
Eoghan