[rest-practices] Atom as a generic container? [was Re: Media types]

[Mark McLoughlin]

On Fri, 2010-04-16 at 10:44 -0700, David Lutterkort wrote:
> On Fri, 2010-04-16 at 08:06 -0400, Bryan Kearney wrote:
> > On 04/16/2010 05:22 AM, Mark McLoughlin wrote:
> > > 
> > > We're talking about the format of the document returned by e.g.
> > > 'GET /vms'. At the moment, we're just doing:
> > >
> > >    <collection>
> > >      <vm>
> > >      </vm>
> > >      ...
> > >    </collection>
> > 
> > 
> > I think an xml structure like this will make it harder for any 
> > auto-clients such as ruby. I would suggest to get <vms/> as the wrapper.
> 
> Even more importantly, I really don't like using atom links for any kind
> of relationship - it's really just window-dressing, and makes _no_
> semantic difference in the XML, i.e.
> 
>         <vm>
>           <link rel='self' href='...'/>
>           <id>myvm</id>
>           $properties
>         </vm>
>         
> has no semantic difference from
> 
>         <vm name='myvm' href='...'>
>           $properties
>         </vm>
> 
> except that it makes processing references, i.e. a representation that
> has only the id and a link, much more annoying, at least in Ruby.

Could you give some example code, maybe? I've just had a quick look at
the ruby rest client, and it's not immediately obvious what you mean

> The code to take the first form and turn it into an object that
> lazy-loads the full properties when given only a reference, you have a
> much harder time distinguishing between a reference and the full
> representation (what precisely do you do to determine if $properties is
> there or not ? Count children of <vm/> ? Look for an element that has to
> be there ? Stick $properties into another container tag ?)

Using e.g. <vm href="..."/> as a 'reference' strikes me as as the real
problem here - you're struggling to tell whether a <vm> node is a
representation of the object, or just a reference to the object

i.e.

  <link rel="some_description_of_the_relationship" href="..."

makes more sense to me than

  <some_description_of_the_relationship>
    <vm href="..." />
  </some_description_of_the_relationship>

and its much more obvious the former is a reference

> In the second form, it's very easy: if <vm/> has no children, it's a
> reference, if it does have children you're looking at the representation
> of the whole object.

Alternative for this 'lazy loading' thing: if <vm/> has a single
rel="self" <link/>, it is incomplete

> Atom-style links are nice for references to URL's that are not some sort
> of object in the system,

What are they, then? By giving them a URI, we're modelling actions as
objects too :-)

> but they're not a particularly nice way to handle object references.

Bill makes the case for Atom links in his book and I agree it makes some
sense. But I actually don't particularly care - we're designing a new
API and trying to stick with the 'consensus approach' rather than going
and re-inventing the wheel.

Cheers,
Mark.