[rest-practices] Links for actions

[David Lutterkort]

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.

> 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.

I wonder how many clients will implement this kind of error recovery
properly ;)

David