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

[David Lutterkort]

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. 

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 ?)

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.

Atom-style links are nice for references to URL's that are not some sort
of object in the system, but they're not a particularly nice way to
handle object references.

David