[rest-practices] Links for actions

[Mark McLoughlin]

On Wed, 2010-05-12 at 01:43 -0400, Itamar Heim wrote:
> > From: rest-practices-bounces at redhat.com [mailto:rest-practices-
> > bounces at redhat.com] On Behalf Of David Lutterkort
> ...
> > 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>
> [IH] just wondering, so if I ask for a list of 500 instances, I will get
> all actions possible on all instances 500 times as well?

Yes

If it becomes an issue, one way around it is to make a collection just
include references e.g.

       <vms>
         <vm id="1" href="/vms/1"/>
         <vm id="2" href="/vms/2"/>
         ...
         <vm id="500" href="/vms/500"/>
       </vms>

or you could include partial representations:

       <vms>
         <vm id="1" href="/vms/1">
           <name>vm1</name>
           <status>UP</status>
         </vm>
         <vm id="2" href="/vms/2"/>
           <name>vm2</name>
           <status>UP</status>
         </vm>
         ...
         <vm id="500" href="/vms/500">
           <name>vm500</name>
           <status>DOWN</status>
         </vm>
       </vms>

> isn't this mixing introspection with data?

Yes, that's a key part of REST's "hypermedia as the engine of
application state" principle

The hypermedia encapsulates not only the current state of the entity,
but also, how its state can be changed

> Unless I'm introspecting the web service, I'm
> implying I actually know what the possible actions are (i.e., I already
> wrote the code that uses them, and needed this data only during
> development time, but I don't need it during runtime[1]).
> 
> [1] unless permissions are implied, and for each instance I can get a
> different list of <actions>.

Right, exactly - the <actions> block would only contain a "reboot"
action if the user had permission to reboot that instance

Cheers,
Mark.