[rest-practices] Links for actions

[Mark McLoughlin]

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.

The idea is that an action *is* a resource - POST is creating an
instance of it

> 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"/>

ITYM:

  <link href="/api/instances/inst1" rel="destroy" method="delete"/>

> Any thoughts on this ?

I don't think "destroy" is an action like the others

To me, it's as implicit that DELETE destroys an instance as it is that
POST creates an instance e.g. you're not adding:

  <instances>
    <actions>
      <link href="/api/instances" rel="create" method="post"/>
    </actions>
    ...
  </instances>

So, IMHO, drop the "destroy" action and have docs like:

  https://fedorahosted.org/rhevm-api/wiki/CommonIdiomsForResources

Cheers,
Mark.