You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@deltacloud.apache.org by Toby Crawley <tc...@redhat.com> on 2010/12/03 19:26:58 UTC
New /api format with exposed capabilities
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
Re: New /api format with exposed capabilities
Posted by David Lutterkort <lu...@redhat.com>.
Just to continue this long standing discussion:
On Wed, 2011-01-12 at 11:53 -0500, Toby Crawley wrote:
> On Dec 3, 2010, at 1:26 PM, Toby Crawley wrote:
> <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>
Instead of thinking of these as legacy entries, think of them as
declaring certain features - I can imagine, that in the future we might
provide more metadata on certain features, e.g. the maximum size of the
user data for the user_data feature.
If we ever do this, I'd like to provide that in only one place, and the
above list of features seems right for that to me.
> <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>
To make it clearer that we are referencing already declared features in
the <operation> tag, we should adjust that XML slightly:
<operation method='get' name='show' scope='member'>
<feature ref='authentication_key'/>
</operation>
If we ever want to get fancy, this feature reference might also get a
body, in which we could, for example, detail some more how the feature
modifies the operation; e.g., that user_data adds a parameter
'user_data' to instance creation.
David
Re: New /api format with exposed capabilities
Posted by Adrian Cole <fe...@gmail.com>.
I think the operation approach w/ deprecated old style makes sense.
>From a jclouds perspective, the win we could have is insight between
features on create vs get (as you've shown) vs update (likely to come
next). It could possibly be better is to have this context-sensitve.
Meaning only show delete when an instance is deletable, and features
like 'stop' only show when the specific instance is stoppable, the
write operations only available for collections that are writeable,
etc.
-A
On Wed, Jan 12, 2011 at 8:53 AM, Toby Crawley <tc...@redhat.com> wrote:
>
> 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
>
>
>
>
>
Re: New /api format with exposed capabilities
Posted by Toby Crawley <tc...@redhat.com>.
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