incubator-deltacloud-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mar...@redhat.com
Subject [PATCH 1/3] Updates the REST API to clarify use of application/x-www-form-urlencoded or application/form-data content types for POST operations. Examples are updated to use urlencoded where appropriate. Also minor tidying up of long lines to < 80 chars
Date Wed, 31 Aug 2011 09:06:59 GMT
From: marios <marios@redhat.com>


Signed-off-by: marios <marios@redhat.com>
---
 site/content/api.mdown |  359 ++++++++++++++++++++++++++++++++----------------
 1 files changed, 243 insertions(+), 116 deletions(-)

diff --git a/site/content/api.mdown b/site/content/api.mdown
index 757332f..a59511d 100644
--- a/site/content/api.mdown
+++ b/site/content/api.mdown
@@ -128,6 +128,7 @@ Storage Snapshots, Blob Storage.
 <br/>
 * * *
 
+<a name=authentication>.
 ### 1.3 Authentication
 
 The Deltacloud API server is stateless, and does not keep any information
@@ -138,7 +139,8 @@ and clients have to send the username/password for the backend cloud on
every re
 The specifics of what needs to be sent varies from cloud to cloud; some
 cloud providers employ a username and password for API access, whilst
 others use special-purpose API keys. A list of the credentials that a given
-cloud provider expects for API access is [available here](documentation.html)
+cloud provider expects for API access is
+[available here](documentation.html#credentials)
 
 <br/>
 [Contents](#toc)
@@ -443,10 +445,10 @@ to EC2 "availability zones":
 
 #### `GET /api/realms/:id`
 
-Provide the details of a ***realm***. Currently, these are a ***name***, a  ***state*** and
a
- ***limit** applicable to the current requester. The ***name*** is an arbitrary label
-with no specific meaning in the API. The ***state*** can be either ***AVAILABLE***
- or ***UNAVAILABLE***. The example below shows the ***realm*** for the Rackspace driver.
+Provide the details of a ***realm***. Currently, these are a **name**, a  **state** and a
+ **limit** applicable to the current requester. The ***name*** is an arbitrary label
+with no specific meaning in the API. The **state** can be either **AVAILABLE**
+ or **UNAVAILABLE**. The example below shows the ***realm*** for the Rackspace driver.
 Since Rackspace does not currently have a notion of ***realms*** the Deltacloud
 Rackspace driver provides a single ***realm*** called 'US', signifying that all
 compute resources for that cloud provider are hosted in the United States:
@@ -668,6 +670,7 @@ whereas Rackspace Cloudservers ***image*** state can be one of *UNKNOWN*,
*PREPA
 attribute that specifies the URI to which a client may issue a **HTTP POST** for creation
of
 an ***instance*** from the given ***image***.
 
+<a name=list_images>.
 #### `GET /api/images`
 
 Return a list of all ***images*** available in the back-end cloud. By default this call will
@@ -787,13 +790,15 @@ the new image. For example:
     ...
 
 To create a new ***image*** the client must specify the *instance_id* of the running instance.
- Optionally, the client may also provide a *name* and a *description*. The parameters are
-specified as multipart/form-data fields in the client POST. The Deltacloud server will
-respond to a successful operation with **HTTP 201 Created** and provide details of the
+ Optionally, the client may also provide a *name* and a *description*. The parameters may
+be specified as multipart/form-data fields in the client POST.
+<!--, as illustrated in the
+example below.  -->
+Alternatively, clients may also specify parameters using a content-type of
+application/x-www-form-urlencoded. The Deltacloud server will respond to a
+successful operation with **HTTP 201 Created** and provide details of the
 newly created ***image***:
 
-
-
 `Example request:`
 
     POST /api/images?format=xml HTTP/1.1
@@ -801,7 +806,12 @@ newly created ***image***:
     User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
     Host: localhost:3002
     Accept: */*
-    Content-Length: 404
+    Content-Length: 96
+    Content-Type: application/x-www-form-urlencoded
+
+    instance_id=20109341&name=customisedserver&description=jsmith%20cu
+    stomised%20web%20server%20July%2021%202011
+<!--
     Expect: 100-continue
     Content-Type: multipart/form-data; boundary=----------------------------ba9acb193034
 
@@ -817,8 +827,7 @@ newly created ***image***:
     Content-Disposition: form-data; name="description"
 
     jsmith customised web server July 21 2011
-    ------------------------------ba9acb193034--
-
+    ------------------------------ba9acb193034-->
 
 `Server response:`
 
@@ -1355,22 +1364,29 @@ IP address. This access may be given using the [firewalls](#firewalls)
collectio
 <a name=create_instance>.
 #### `POST /api/instances`
 
-Create a new ***instance***. At a minimum clients must specify the ***image*** from
-which the virtual machine ***instance*** is to be created. Optionally a client
-may also specify a ***hardware profile*** and ***realm*** (with default values used
-otherwise). Clients can also provide a *name* for the new *instance* though this is not
-supported by all back-end cloud providers. Whether a given feature is available is advertised
-in the response to the Deltacloud server API entry point.
-The details of the new ***instance*** are returned in response to this operation.
-
-For creation of an ***instance*** in the Amazon EC2 cloud a client can also specify the
-name of the EC2 keypair to be used as well as the firewalls (EC2 security groups) that the
-***instance*** should be launched into. The EC2 keypair is specified with the parameter *keyname*
-while firewalls are specified sequentially as *firewalls1* ... *firewalls2* ... etc. These
parameters
-are specified in the first ***instance*** creation example below. Note that the values for
-public and private addresses are blank in the server response, as these have not yet been
-assigned by the cloud provider. Subsequent requests for the ***instance*** details
-will provide these values.
+Create a new ***instance***. At a minimum clients must specify the ***image***
+from which the virtual machine ***instance*** is to be created. Optionally a
+client may also specify a ***hardware profile*** and ***realm*** (with default
+values used otherwise). Clients can also provide a *name* for the new *instance*
+ though this is not supported by all back-end cloud providers. Whether a given
+feature is available is advertised in the response to the Deltacloud server
+API entry point. The details of the new ***instance*** are returned in
+response to this operation.
+
+For creation of an ***instance*** in the Amazon EC2 cloud a client can also
+specify the name of the EC2 keypair to be used as well as the firewalls
+(EC2 security groups) that the ***instance*** should be launched into. The
+EC2 keypair is specified with the parameter *keyname* while firewalls are
+specified sequentially as *firewalls1* ... *firewalls2* ... etc. These parameters
+are specified in the first ***instance*** creation example below. Note that the
+values for public and private addresses are blank in the server response, as
+these have not yet been assigned by the cloud provider. Subsequent requests
+for the ***instance*** details will provide these values.
+
+In the first example client request shown below, parameters are specified as
+multipart/form-data. A client may also alternatively specify the same parameters
+using the x-www-url-form-urlencoded content type, as demonstrated by the
+[second example](#create_instance_rax) below.
 
 <a name=create_instance_ec2>.
 
@@ -1444,11 +1460,14 @@ will provide these values.
       </authentication>
     </instance>
 
+<a name=create_instance_rax>.
+
 The second example given below shows creation of an ***instance*** in the Rackspace
 Cloudservers cloud. Here you can see that the client provides the optional *name*
  parameter and that the created instance uses authentication of type **password**.
-The *username* and *password* are returned with the details of the newly created
-***instance***:
+Furthermore, in this example the requesting client uses a content-type of
+application/x-www-form-urlencoded. The *username* and *password* are returned with
+the details of the newly created ***instance***:
 
 `Example request: (Rackspace Cloudservers)`
 
@@ -1457,6 +1476,11 @@ The *username* and *password* are returned with the details of the
newly created
     User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
     Host: localhost:3002
     Accept: */*
+    Content-Length: 34
+    Content-Type: application/x-www-form-urlencoded
+
+    image_id=53&hwp_id=1&name=myserver
+<!--
     Content-Length: 342
     Expect: 100-continue
     Content-Type: multipart/form-data; boundary=----------------------------7424b11a955d
@@ -1473,7 +1497,7 @@ The *username* and *password* are returned with the details of the newly
created
     Content-Disposition: form-data; name="name"
 
     myserver
-    ------------------------------7424b11a955d--
+    ------------------------------7424b11a955d-->
 
 `Server response:`
 
@@ -1601,13 +1625,20 @@ Gogrid cloud:
 #### `POST /api/keys`
 
 Some back-end cloud providers allow a client to create new credentials for
-accessing Instances. The parameters (key attributes) required by this function will depend
on the
- back-end and are specified in the relevant driver. At present only the Amazon EC2 cloud
implements a key
-create method and this requires the key *name* to be specified as a parameter. It should
be noted that
-the private key attribute of a newly created key is reported only once, in response to the
create
-operation as shown in the example below. The client should save the private key for future
use with
- ***instance*** authentication. In all subsequent calls, only the fingerprint attribute is
displayed
- in the Deltacloud server response, as illustrated by the [GET /api/keys](#get_keys) call
above.
+accessing Instances. The parameters (key attributes) required by this function
+will depend on the back-end and are specified in the relevant driver. At
+present only the Amazon EC2 cloud implements a key create method and this
+requires the key *name* to be specified as a parameter. It should be noted that
+the private key attribute of a newly created key is reported only once, in
+response to the create operation as shown in the example below.
+The client should save the private key for future use with  ***instance***
+authentication. In all subsequent calls, only the fingerprint attribute
+is displayed in the Deltacloud server response, as illustrated by
+the [GET /api/keys](#get_keys) call above.
+
+Note that as with other HTTP POST calls in the Deltacloud REST API, client requests
+may specify the required parameters as multipart/form-data, or using the
+application/x-www-form-urlencoded content type.
 
 <a name=key_create>.
 
@@ -1618,6 +1649,11 @@ operation as shown in the example below. The client should save the
private key
     User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
     Host: localhost:3001
     Accept: */*
+    Content-Length: 19
+    Content-Type: application/x-www-form-urlencoded
+
+    name=jsmith_new_key
+<!--
     Content-Length: 153
     Expect: 100-continue
     Content-Type: multipart/form-data; boundary=----------------------------92fbd163f915
@@ -1626,7 +1662,7 @@ operation as shown in the example below. The client should save the
private key
     Content-Disposition: form-data; name="name"
 
     jsmith_new_key
-    ------------------------------92fbd163f915--
+    ------------------------------92fbd163f915-->
 
 `Server response:`
 
@@ -1839,9 +1875,12 @@ Retrieve details of a single specified ***firewall***.
 
 #### `POST /api/firewalls`
 
-Creates a new ***firewall***. Clients must specify the ***firewall*** *name* and *description*
as
-parameters to the request. On succesful completion the Deltacloud server will respond with
**HTTP 201
-Created** and return details of the newly created ***firewall***:
+Creates a new ***firewall***. Clients must specify the ***firewall*** *name*
+and *description* as parameters to the request. On succesful completion the
+Deltacloud server will respond with **HTTP 201 Created** and return details
+of the newly created ***firewall***. As with other POST operations in the
+Deltacloud API, a client may specify parameters as multipart/form-data or using
+the application/x-www-form-urlencoded content-type.
 
 `Example request:`
 
@@ -1850,19 +1889,24 @@ Created** and return details of the newly created ***firewall***:
     User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
     Host: localhost:3001
     Accept: */*
+    Content-Length: 64
+    Content-Type: application/x-www-form-urlencoded
+
+    name=Devel_Group&description=Access%20for%20all%20development%20machines
+<!--
     Content-Length: 285
     Expect: 100-continue
     Content-Type: multipart/form-data; boundary=----------------------------cdbcabd8ab04
 
     ------------------------------cdbcabd8ab04
     Content-Disposition: form-data; name="name"
-
+-->
     Devel_Group
     ------------------------------cdbcabd8ab04
     Content-Disposition: form-data; name="description"
 
     Access for all development machines
-    ------------------------------cdbcabd8ab04--
+    ------------------------------cdbcabd8ab04 -->
 
 `Server response:`
 
@@ -1880,7 +1924,7 @@ Created** and return details of the newly created ***firewall***:
       </rules>
     </firewall>
 
-<a name=delete_firewall_rule> .
+<a name=delete_firewall> .
 
 #### `DELETE /api/firewalls/:id`
 
@@ -1939,17 +1983,23 @@ In both cases the error message is propagated from the back-end cloud
provider t
 
 #### `POST /api/firewalls/:id/rules`
 
-Create a new ***firewall rule*** within a specified ***firewall***. A client must supply
the **protocol**
-(one of *udp*, *tcp* or *icmp*), **port_from** and **port_to** as parameters. Ofcourse the
client must also
-specify the **sources** to which the given rule is to apply. IP addresses are specified in
CIDR format
-sequentially: *ip_address1=192.168.10.10/24*, *ip_address2=10.1.1.1/16* ... *ip_addressN=...*.
The IP
-address '0.0.0.0/0' acts as a wildcard to specify **any** IP address.
-Source ***firewalls*** are also specified sequentially but the *owner_id* of the ***firewall***
that is to
- be authorized must also be supplied (this is an Amazon EC2 requirement): group1=name1,
-group1owner=1234567890, group2=name2, group2owner=0987654321, ... groupN=nameN, groupNowner=...
-
-The Deltacloud server responds with a **HTTP 201 Created** after a successful operation together
with the
-details of the affected ***firewall***:
+Create a new ***firewall rule*** within a specified ***firewall***. A client
+must supply the **protocol** (one of *udp*, *tcp* or *icmp*), **port_from**
+and **port_to** as parameters. Ofcourse the client must also specify the
+**sources** to which the given rule is to apply. IP addresses are specified
+in CIDR format sequentially: *ip_address1=192.168.10.10/24*,
+*ip_address2=10.1.1.1/16* ... *ip_addressN=...*. The IP address '0.0.0.0/0'
+acts as a wildcard to specify **any** IP address. Source ***firewalls*** are
+also specified sequentially but the *owner_id* of the ***firewall*** that is
+to be authorized must also be supplied (this is an Amazon EC2 requirement):
+group1=name1, group1owner=1234567890, group2=name2, group2owner=0987654321,
+... groupN=nameN, groupNowner=...
+
+The Deltacloud server responds with a **HTTP 201 Created** after a successful
+operation together with the details of the affected ***firewall***. The example
+client request below specifies the required parameters as multipart/form-data.
+However clients may also legitimately use the application/x-www-form-urlencoded
+to provide firewall rule parameters.
 
 `Example request:`
 
@@ -2027,6 +2077,8 @@ details of the affected ***firewall***:
       </rules>
     </firewall>
 
+<a name=delete_firewall_rule> .
+
 #### `DELETE /api/firewalls/:id/:rule_id`
 
 Delete the specified firewall rule. The Deltacloud server will respond with **HTTP 204 No
Content** on
@@ -2177,12 +2229,14 @@ succesful operation.
 
 #### `POST /api/addresses/:id/associate`
 
-This operation associates a given ***address*** with a running ***instance***. The client
must
-specify the *instance_id* as a parameter to this call. For Amazon EC2, the specified ***address***
-will replace the currently assigned *public_address* of the ***instance***. A succesful operation
will
-produce a **HTTP 202 Accepted** response:
-
-
+This operation associates a given ***address*** with a running ***instance***.
+The client must specify the *instance_id* as a parameter to this call.
+For Amazon EC2, the specified ***address*** will replace the currently assigned
+*public_address* of the ***instance***. A succesful operation will produce a
+**HTTP 202 Accepted** response. The example client request below specifies the
+required  *instance_id* parameter using the application/x-www-form-urlencoded
+content-type, however this can also legitimately be specified using
+multipart/form-data.
 
 `Example request:`
 
@@ -2191,6 +2245,12 @@ produce a **HTTP 202 Accepted** response:
     User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
     Host: localhost:3001
     Accept: */*
+    Content-Length: 22
+    Content-Type: application/x-www-form-urlencoded
+
+    instance_id=i-9d8a3dfc
+
+<!--
     Content-Length: 156
     Expect: 100-continue
     Content-Type: multipart/form-data; boundary=----------------------------e4c1d4718683
@@ -2199,7 +2259,7 @@ produce a **HTTP 202 Accepted** response:
     Content-Disposition: form-data; name="instance_id"
 
     i-9d8a3dfc
-    ------------------------------e4c1d4718683--
+    ------------------------------e4c1d4718683-->
 
 `Server response:`
 
@@ -2362,12 +2422,16 @@ Retrieve details for a specific load balancer:
 
 #### `POST /api/load_balancers`
 
-This operation creates a new ***load_balancer***. Clients must provide the ***load_balancer***
**name**,
- the **realm_id** to which the balancer is to apply, a **listener_protocol** which the balancer
will
-respond to (one of **HTTP** or **TCP**), the **listener_balancer_port** which specifies the
port
-that the ***load_balancer*** will be expecting network traffic on and finally the **listener_instance_port**
-which specifies the port on which ***instances*** will be receiving network traffic forwarded
by the
-***load_balancer***.
+This operation creates a new ***load_balancer***. Clients must provide the
+***load_balancer*** **name**, the **realm_id** to which the balancer is to
+apply, a **listener_protocol** which the balancer will respond to (one of
+**HTTP** or **TCP**), the **listener_balancer_port** which specifies the port
+that the ***load_balancer*** will be expecting network traffic on and finally
+the **listener_instance_port** which specifies the port on which ***instances***
+will be receiving network traffic forwarded by the ***load_balancer***. As with
+other operations in the Deltacloud API, parameters may be specified by a requesting
+client using multipart/form-data or as application/x-www-form-urlencoded data
+as shown below:
 
 `Example request:`
 
@@ -2376,6 +2440,13 @@ which specifies the port on which ***instances*** will be receiving
network traf
     User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
     Host: localhost:3001
     Accept: */*
+    Content-Length: 121
+    Content-Type: application/x-www-form-urlencoded
+
+    name=webtraffic-balancer&realm_id=us-east-1c&listener_protocol=HTTP&
+    listener_balancer_port=80&listener_instance_port=3001
+
+<!--
     Content-Length: 603
     Expect: 100-continue
     Content-Type: multipart/form-data; boundary=----------------------------395a7b3a9c77
@@ -2400,8 +2471,7 @@ which specifies the port on which ***instances*** will be receiving
network traf
     Content-Disposition: form-data; name="listener_instance_port"
 
     3001
-    ------------------------------395a7b3a9c77--
-
+    ------------------------------395a7b3a9c77-->
 
 `Server response:`
 
@@ -2454,9 +2524,12 @@ server will respond with **HTTP 204 No Content** for a succesful operation:
 
 #### `POST /api/load_balancers/:id/register`
 
-This operation registers a running ***instance*** with a specified ***load_balancer***. Clients
-must provide the **instance_id** as a parameter to the request. The Deltacloud server will
respond
-with a **HTTP 204 No Content** after a succesful operation:
+This operation registers a running ***instance*** with a specified
+***load_balancer***. Clients must provide the **instance_id** as a parameter
+to the request. The Deltacloud server will respond with a **HTTP 204 No Content**
+after a succesful operation. The Deltacloud server will accept client request
+parameters encoded as multipart/form-data or as
+application/x-www-form-urlencoded data.
 
 `Example request:`
 
@@ -2465,6 +2538,12 @@ with a **HTTP 204 No Content** after a succesful operation:
     User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
     Host: localhost:3001
     Accept: */*
+    Content-Length: 22
+    Content-Type: application/x-www-form-urlencoded
+
+    instance_id=i-4f06b52e
+
+<!--
     Content-Length: 156
     Expect: 100-continue
     Content-Type: multipart/form-data; boundary=----------------------------6af752b909b2
@@ -2473,7 +2552,7 @@ with a **HTTP 204 No Content** after a succesful operation:
     Content-Disposition: form-data; name="instance_id"
 
     i-4f06b52e
-    ------------------------------6af752b909b2--
+    ------------------------------6af752b909b2-->
 
 `Server response:`
 
@@ -2482,8 +2561,10 @@ with a **HTTP 204 No Content** after a succesful operation:
 
 #### `POST /api/load_balancers/:id/unregister`
 
-This operation will unregister a specified ***instance*** from the given ***load_balancer***.
The
-client must supply the **instance_id** parameter to identify the ***instance***:
+This operation will unregister a specified ***instance*** from the given
+***load_balancer***. The client must supply the **instance_id** parameter to
+identify the ***instance***, either as multipart/form-data or as
+application/x-www-form-urlencoded data (as shown below).
 
 `Example request:`
 
@@ -2492,6 +2573,11 @@ client must supply the **instance_id** parameter to identify the ***instance***:
     User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
     Host: localhost:3001
     Accept: */*
+    Content-Length: 22
+    Content-Type: application/x-www-form-urlencoded
+
+    instance_id=i-4f06b52e
+<!--
     Content-Length: 156
     Expect: 100-continue
     Content-Type: multipart/form-data; boundary=----------------------------987218f60703
@@ -2500,7 +2586,7 @@ client must supply the **instance_id** parameter to identify the ***instance***:
     Content-Disposition: form-data; name="instance_id"
 
     i-4f06b52e
-    ------------------------------987218f60703--
+    ------------------------------987218f60703-->
 
 `Server response:`
 
@@ -2613,13 +2699,19 @@ This operation retrieves the details for the specified storage_volume:
 
 #### `POST /api/storage_volumes`
 
-This operation will create a new ***storage_volume***. A client may specify a **snapshot_id**
from which
-to instantiate the ***storage_volume*** though this is optional. The **capacity** parameter,
expressed in
-Gigabytes, is also optional and will default to 1 Gigabyte. Finally clients may also specify
the
-**realm_id** as a ***storage_volume*** can typically only be attached to ***instances***
running within
-the specified ***realm***. If the ***realm*** is not specified it will default to the first
realm returned
- by the cloud provider. A succesful operation will return **HTTP 201 Created** with the details
of the newly
-created ***storage_volume***:
+This operation will create a new ***storage_volume***. A client may specify a
+**snapshot_id** from which to instantiate the ***storage_volume*** though this
+is optional. The **capacity** parameter, expressed in Gigabytes, is also optional
+and will default to 1 Gigabyte. Finally clients may also specify the **realm_id**
+as a ***storage_volume*** can typically only be attached to ***instances***
+ running within the specified ***realm***. If the ***realm*** is not specified
+it will default to the first realm returned by the cloud provider.
+A succesful operation will return **HTTP 201 Created** with the details of
+the newly created ***storage_volume***.
+
+As with the other **POST** operations in the Deltacloud API, clients
+may choose to specify operation parameters as multipart/form-data or
+as application/x-www-form-urlencoded data.
 
 
 `Example request:`
@@ -2629,10 +2721,16 @@ created ***storage_volume***:
     User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
     Host: localhost:3001
     Accept: */*
+    Content-Length: 31
+    Content-Type: application/x-www-form-urlencoded
+
+    capacity=10&realm_id=us-east-1c
+
+<!--
     Content-Length: 252
     Expect: 100-continue
     Content-Type: multipart/form-data; boundary=----------------------------90dea979a9f4
-
+--
     ------------------------------90dea979a9f4
     Content-Disposition: form-data; name="capacity"
 
@@ -2641,7 +2739,7 @@ created ***storage_volume***:
     Content-Disposition: form-data; name="realm_id"
 
     us-east-1c
-    ------------------------------90dea979a9f4--
+    ------------------------------90dea979a9f4-->
 
 `Server response:`
 
@@ -2710,13 +2808,17 @@ attached to an ***instance***.
 
 #### `POST /api/storage_volumes/:id/attach`
 
-This operation will attach the specified ***storage_volume*** to a running ***instance***.
Clients must
-specify the **instance_id** and the **device** as parameters. The **device** parameter is
used as the
-'mount point', that is, the location at which the ***storage_volume*** will be exposed to
the given
-***instance*** (e.g., /dev/sdh). The Deltacloud server will respond with a **HTTP 202 Accepted**
after
-a succesful attach operation together with details of the ***storage_volume***. Note in the
example
- below that the **state** is reported as 'unknown' although the **mount** element is present,
as the
+This operation will attach the specified ***storage_volume*** to a running
+***instance***. Clients must specify the **instance_id** and the **device**
+as parameters. The **device** parameter is used as the 'mount point', that is,
+ the location at which the ***storage_volume*** will be exposed to the given
+***instance*** (e.g., /dev/sdh). The Deltacloud server will respond with a
+**HTTP 202 Accepted** after a succesful attach operation together with details
+of the ***storage_volume***. Note in the example below that the **state** is
+reported as 'unknown' although the **mount** element is present, as the
 processing has not yet been completed (hence the **202** status code).
+Clients may specify the required parameters as multipart/form-data
+or as application/x-www-form-urlencoded data.
 
 `Example request:`
 
@@ -2725,10 +2827,16 @@ processing has not yet been completed (hence the **202** status code).
     User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
     Host: localhost:3001
     Accept: */*
+    Content-Length: 38
+    Content-Type: application/x-www-form-urlencoded
+
+    instance_id=i-b100b3d0&device=/dev/sdi
+
+<!--
     Content-Length: 259
     Expect: 100-continue
     Content-Type: multipart/form-data; boundary=----------------------------5a074e9c5fcc
-
+--
     ------------------------------5a074e9c5fcc
     Content-Disposition: form-data; name="instance_id"
 
@@ -2737,7 +2845,7 @@ processing has not yet been completed (hence the **202** status code).
     Content-Disposition: form-data; name="device"
 
     /dev/sdi
-    ------------------------------5a074e9c5fcc--
+    ------------------------------5a074e9c5fcc-->
 
 `Server response:`
 
@@ -2891,10 +2999,12 @@ Get all details for a specified ***storage snapshot***, as shown below:
 
 #### `POST /api/storage_snapshots`
 
-This operation will create a new ***storage_snapshot***. Clients must specify the ***storage_volume***
-from which the snapshot is to be created, by supplying the **volume_id** parameter. The Deltacloud
-server responds with **HTTP 201 Created** after a succesful operation and provides details
of the
-newly created ***storage_snapshot***:
+This operation will create a new ***storage_snapshot***. Clients must specify
+the ***storage_volume*** from which the snapshot is to be created, by supplying
+the **volume_id** parameter. The Deltacloud server responds with
+**HTTP 201 Created** after a succesful operation and provides details of the
+newly created ***storage_snapshot***. Clients may specify operation parameters as
+multipart/form-data, or as application/x-www-form-urlencoded data:
 
 `Example request:`
 
@@ -2903,6 +3013,12 @@ newly created ***storage_snapshot***:
     User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
     Host: localhost:3001
     Accept: */*
+    Content-Length: 22
+    Content-Type: application/x-www-form-urlencoded
+
+    volume_id=vol-99fbe5f2
+
+<!--
     Content-Length: 156
     Expect: 100-continue
     Content-Type: multipart/form-data; boundary=----------------------------91f7fa88be76
@@ -2911,7 +3027,7 @@ newly created ***storage_snapshot***:
     Content-Disposition: form-data; name="volume_id"
 
     vol-99fbe5f2
-    ------------------------------91f7fa88be76--
+    ------------------------------91f7fa88be76-->
 
 `Server response:`
 
@@ -3035,19 +3151,21 @@ that it contains.
 
 #### `POST /api/buckets`
 
-Creates a new ***bucket*** and requires that you specify the ***name*** as a parameter,
-in the form of multipart/form-data (i.e., HTTP form field). Optionally for Amazon S3
-buckets, you can specify a bucket location with the ***location*** parameter, as per
+Creates a new ***bucket*** and requires that you specify the ***name*** as a
+parameter. Optionally for Amazon S3 buckets, you can specify a bucket location
+with the ***location*** parameter, as per
  [Regions and Endpoints for Amazon Simple Storage Service](http://docs.amazonwebservices.com/general/latest/gr/index.html?rande.html
"AWS Regions and Endpoints");
 valid values for S3 bucket *location* parameter are: "us-west-1", "EU",
 "ap-southeast-1", "ap-northeast-1" (while not specifying a location defaults to
-the "US Standard" region).
+the "US Standard" region). Note that clients may specify parameters as
+multipart/form-data or using a content-type of application/x-www-form-urlencoded.
 
-On succesful creation this call will return a ***201*** HTTP status, specifying the URI
-of the newly created bucket in the **Location** header and the newly created
-***bucket*** object in the response message body. The example request below creates a
-new ***bucket*** in the *EU (Ireland)* region. If the given backend cloud does not
-support locations then the *location* parameter is silently ignored.
+On succesful creation this call will return a ***201*** HTTP status, specifying
+the URI of the newly created bucket in the **Location** header and the newly
+created ***bucket*** object in the response message body. The example request
+below creates a new ***bucket*** in the *EU (Ireland)* region. If the given
+backend cloud does not support locations then the *location* parameter is
+silently ignored.
 
 `Example request:`
 
@@ -3056,18 +3174,25 @@ support locations then the *location* parameter is silently ignored.
     User-Agent: curl/7.20.1
     Host: localhost:3001
     Accept: */*
+    Content-Length: 31
+    Content-Type: application/x-www-form-urlencoded
+
+    name=mybucketeurope&location=EU
+
+
+<!--
     Content-Length: 252
     Content-Type: multipart/form-data; boundary=----------------------------4e90611c39f2
 
     ------------------------------4e90611c39f2
     Content-Disposition: form-data; name="name"
-
+--
     mybucketeurope
     ------------------------------4e90611c39f2
     Content-Disposition: form-data; name="location"
 
     EU
-    ------------------------------4e90611c39f2--
+    ------------------------------4e90611c39f2-->
 
 `Server response:`
 
@@ -3082,6 +3207,7 @@ support locations then the *location* parameter is silently ignored.
       <size>0</size>
     </bucket>
 
+<a name=delete_bucket>.
 #### `DELETE /api/buckets/:id`
 
 Deletes the specified ***bucket***, which must be empty (otherwise the call will
@@ -3162,6 +3288,7 @@ filename=blob_name* in the HTTP response headers.
 
     <BLOB DATA HERE>
 
+<a name=create_blob>.
 #### `PUT /api/buckets/:bucket_id/:blob_id`
 
 Creates a ***blob*** object and sets its content. If the ***blob*** already exists then
@@ -3214,8 +3341,8 @@ The deltacloud server also responds to an alternative `POST` route for
creating
 updating a ***blob*** object. As with the `PUT` method for creating/updating a
 ***blob***, the client must specify the ***bucket*** in which the ***blob*** is to
 be created through the call URI (i.e. you `POST` to the specified ***bucket***).
-The rest of the required fields, that is, the ***blob_id*** (name of the blob),
-the  ***blob_data*** and the ***content-length*** are specified by the client as
+The rest of the required fields, that is, the name of the ***blob***, the
+ ***blob_data*** and the ***content-length*** are specified by the client as
 ***multipart/form-data*** (i.e. in `HTTP POST` form fields).
 
 In order to specify the optional user metadata for a given ***blob*** the client
@@ -3240,12 +3367,12 @@ deltacloud HTML interface (provided for testing purposes).
     Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
     User-Agent: curl/7.20.1 (i386-redhat-linux-gnu) libcurl/7.20.1 N
     Accept: */*
-    Content-Length: 113584
+    Content-Length: 113582
     Expect: 100-continue
     Content-Type: multipart/form-data; boundary=----------------------------517f5f2df858
 
     ------------------------------517f5f2df858
-    Content-Disposition: form-data; name="blob_id"
+    Content-Disposition: form-data; name="blob"
 
     12Jul2011blob
     ------------------------------517f5f2df858
-- 
1.7.3.4


Mime
View raw message