You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@deltacloud.apache.org by ma...@redhat.com on 2011/08/31 11:06:59 UTC
[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
From: marios <ma...@redhat.com>
Signed-off-by: marios <ma...@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
Re: [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
Posted by David Lutterkort <lu...@redhat.com>.
On Wed, 2011-08-31 at 12:06 +0300, marios@redhat.com wrote:
> From: marios <ma...@redhat.com>
>
>
> Signed-off-by: marios <ma...@redhat.com>
> ---
> site/content/api.mdown | 359 ++++++++++++++++++++++++++++++++----------------
> 1 files changed, 243 insertions(+), 116 deletions(-)
Looks good. I would remove all the stuff in HTML comments right now,
though; it's unlikely we'll want to resurrect it.
I would also, for all the requests that accept
application/x-www-form-urlencoded, only give an example using that, and
omit a multipart/form-data example.
ACK either way
David