Return-Path: 
 <deltacloud-dev-return-750-apmail-incubator-deltacloud-dev-archive=incubator.apache.org@incubator.apache.org>
Delivered-To: apmail-incubator-deltacloud-dev-archive@minotaur.apache.org
Received: (qmail 39494 invoked from network); 3 Dec 2010 18:27:29 -0000
Received: from unknown (HELO mail.apache.org) (140.211.11.3)
  by 140.211.11.9 with SMTP; 3 Dec 2010 18:27:29 -0000
Received: (qmail 20689 invoked by uid 500); 3 Dec 2010 18:27:29 -0000
Delivered-To: apmail-incubator-deltacloud-dev-archive@incubator.apache.org
Received: (qmail 20669 invoked by uid 500); 3 Dec 2010 18:27:29 -0000
Mailing-List: contact deltacloud-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
List-Help: <mailto:deltacloud-dev-help@incubator.apache.org>
List-Unsubscribe: <mailto:deltacloud-dev-unsubscribe@incubator.apache.org>
List-Post: <mailto:deltacloud-dev@incubator.apache.org>
List-Id: <deltacloud-dev.incubator.apache.org>
Reply-To: deltacloud-dev@incubator.apache.org
Delivered-To: mailing list deltacloud-dev@incubator.apache.org
Received: (qmail 20661 invoked by uid 99); 3 Dec 2010 18:27:29 -0000
Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230)
    by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 03 Dec 2010 18:27:29 +0000
X-ASF-Spam-Status: No, hits=-5.0 required=10.0
	tests=RCVD_IN_DNSWL_HI,SPF_HELO_PASS,SPF_PASS
X-Spam-Check-By: apache.org
Received-SPF: pass (nike.apache.org: domain of tcrawley@redhat.com designates
 209.132.183.28 as permitted sender)
Received: from [209.132.183.28] (HELO mx1.redhat.com) (209.132.183.28)
    by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 03 Dec 2010 18:27:21 +0000
Received: from int-mx02.intmail.prod.int.phx2.redhat.com
 (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12])
	by mx1.redhat.com (8.13.8/8.13.8) with ESMTP id oB3IQxZq012431
	(version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK)
	for <deltacloud-dev@incubator.apache.org>; Fri, 3 Dec 2010 13:26:59 -0500
Received: from [10.3.113.116] (ovpn-113-116.phx2.redhat.com [10.3.113.116])
	by int-mx02.intmail.prod.int.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id
 oB3IQw4b019831
	for <deltacloud-dev@incubator.apache.org>; Fri, 3 Dec 2010 13:26:58 -0500
Message-ID: <4CF93672.1010901@redhat.com>
Date: Fri, 03 Dec 2010 13:26:58 -0500
From: Toby Crawley <tcrawley@redhat.com>
Reply-To: tcrawley@redhat.com
Organization: Red Hat
User-Agent: Mozilla/5.0 (X11; U; Linux x86_64; en-US;
 rv:1.9.2.12) Gecko/20101103 Fedora/1.0-0.33.b2pre.fc14 Thunderbird/3.1.6
MIME-Version: 1.0
To: deltacloud-dev@incubator.apache.org
Subject: New /api format with exposed capabilities
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
X-Scanned-By: MIMEDefang 2.67 on 10.5.11.12
X-Virus-Checked: Checked by ClamAV on apache.org

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