deltacloud-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Toby Crawley <tcraw...@redhat.com>
Subject Re: New /api format with exposed capabilities
Date Wed, 12 Jan 2011 16:53:29 GMT

On Dec 3, 2010, at 1:26 PM, Toby Crawley wrote:

> Based on rabbit being able to now inspect the operations provided by a
> driver (using capabilities), we have the ability to inform the client
> of the available operations. Based on feedback from David [1], I've
> modified the top level /api response to advertise the available
> operations:
> 
> <api driver='ec2' version='0.2'>
>  <link href='http://localhost:3001/api/instances' rel='instances'>
>    <operation method='get' name='show' scope='member'>
>      <feature name='authentication_key'></feature>
>    </operation>
>    <operation method='delete' name='destroy' scope='member'/>
>    <operation method='post' name='stop' scope='member'/>
>    <operation method='post' name='reboot' scope='member'/>
>    <operation method='post' name='create' scope='collection'>
>      <feature name='user_data'></feature>
>      <feature name='authentication_key'></feature>
>      <feature name='security_group'></feature>
>      <feature name='register_to_load_balancer'></feature>
>    </operation>
>    <operation method='get' name='index' scope='collection'/>
>  </link>
> 
>  [snip]
> 
> </api>
> 
> Since features are declared on a per operation basis, I nested them
> under each operation.
> 
> With this change, I believe it may give a client enough information to
> fully configure itself dynamically, and not have to make too many
> assumptions about operations and operation methods.
> 
> I wanted to get some feedback on this before continuing with the work
> on the client to parse and use this new entry point format. How does
> this new format look?
> 
> Would you prefer that the operation/feature collections be nested
> under operations/features tags?
> 
> example:
> <operations>
>  <operation ...>
>    <features>
>      <feature .../>
>    </features>
>  </operation>
> </operations>
> 
> To me, it's just noise, but if it makes it easier for some libraries/
> langs to parse, I'm fine with adding it.
> 
> Toby
> 
> [1] http://mail-archives.apache.org/mod_mbox/incubator-deltacloud-dev/201011.mbox/%3C1289524532.4164.1306.camel@avon.watzmann.net%3E


David pointed out that this breaks api compatibility - so here is an alternate /api response
that should maintain compatibility assuming the clients are properly parsing the xml and ignoring
elements they don't recognize (is that a safe assumption? This format should work with the
existing ruby client, though I haven't tested it).

<api driver='ec2' version='0.2'>
 <link href='http://localhost:3001/api/instances' rel='instances'>
   <feature name='authentication_key'></feature>
   <feature name='user_data'></feature>
   <feature name='authentication_key'></feature>
   <feature name='security_group'></feature>
   <feature name='register_to_load_balancer'></feature>

   <operation method='get' name='show' scope='member'>
     <feature name='authentication_key'></feature>
   </operation>
   <operation method='delete' name='destroy' scope='member'/>
   <operation method='post' name='stop' scope='member'/>
   <operation method='post' name='reboot' scope='member'/>
   <operation method='post' name='create' scope='collection'>
     <feature name='user_data'></feature>
     <feature name='authentication_key'></feature>
     <feature name='security_group'></feature>
     <feature name='register_to_load_balancer'></feature>
   </operation>
   <operation method='get' name='index' scope='collection'/> 
  </link>

 [snip]

</api>

This format leaves the <feature>'s in their original location, and also nests them under
their corresponding operations for clients that want to be aware of the available operations
and the features for each operation. For comparison, the current api response would be:

<api driver='ec2' version='0.1.0'>
 <link href='http://localhost:3001/api/instances' rel='instances'>
   <feature name='authentication_key'></feature>
   <feature name='user_data'></feature>
   <feature name='authentication_key'></feature>
   <feature name='security_group'></feature>
   <feature name='register_to_load_balancer'></feature>
  </link>

 [snip]

</api>

Thoughts?

---
Toby Crawley
tcrawley@redhat.com





Mime
View raw message