[rest-practices] ID as an attribute [was Re: [deltacloud-devel] Towards declaring the Deltacloud API stable]

[David Lutterkort]

On Wed, 2010-05-12 at 10:44 +0100, Mark McLoughlin wrote:
> On Thu, 2010-05-06 at 21:47 +0100, Mark McLoughlin wrote:
> 
> > Related, with the RHEV-M API we're experimenting with making both the
> > id and href attributes, which would work out nice here:
> > 
> >   GET /api/images HTTP/1.1
> > 
> >   <images>
> >     <image id="1234" href="/api/images/1234"/>
> >     <image id="9876" href="/api/images/9876"/>
> >     ...
> >   </images>
> > 
> > rather than:
> > 
> >   GET /api/images HTTP/1.1
> > 
> >   <images>
> >     <image href="/api/images/1234">
> >       <id>1234</id>
> >     </image>
> >     <image href="/api/images/9876">
> >       <id>9876</id>
> >     </image>
> >     ...
> >   </images> 
> 
> Just wanted to bring this up again - it got lost in the mix
> 
> I don't feel very strongly about it either way, but I do prefer:
> 
>   POST /storagedomains/1234/attachments HTTP/1.1
> 
>   <attachment><datacenter id="5678"/></attachment>
> 
> over:
> 
>   POST /storagedomains/1234/attachments HTTP/1.1
> 
>   <attachment><datacenter><id>"5678"</id></datacenter></attachment>

/me too. I have some hesitation about an 'id' attribute, simply because
it has a very special meaning in HTML (and some XML schemata); I was
thinking of using the following scheme for references in the Deltacloud
API:

  <element href="..." key="..." label="..."/>

corresponding to the three types of identifiers listed in [1], where
href has a URL, key has some sort of primary key (often the last part of
the URL, but clients don't need to care about that), and label the
human-readable identifier. For most Deltacloud objects, there will
actually not be a label.

David

[1] http://fedoraproject.org/wiki/Cloud_APIs_REST_Style_Guide#Identifiers


David