[rest-practices] Links for actions

[Mark McLoughlin]

Hi David,

On Wed, 2010-05-12 at 10:23 +0100, Mark McLoughlin 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.
> 
> 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

Any more thoughts?

Given that the use of GET, POST and PUT is implied, I guess I just don't
understand what's special about DELETE that we'd have a <link> to
describe it

Btw, I've added a section to the style guide:

  https://fedoraproject.org/wiki/Cloud_APIs_REST_Style_Guide#CRUD

Cheers,
Mark.