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/22 15:40:47 UTC
Clarify API Docs on use of multipart/form-data
Deltacloud API accepts request parameters for POST operations as either
multipart/form-data or application/x-www-form-urlencoded. Current API
Docs show all examples with multipart/form-data. This patch clarifies
that urlencoded parameters can also be used for POST operations,
marios
[PATCH] Clarify the optional use of application/x-www-form-urlencoded for POST operation parameters in the Deltacloud API Docs (site).
Posted by ma...@redhat.com.
From: marios <ma...@redhat.com>
Signed-off-by: marios <ma...@redhat.com>
---
site/content/api.mdown | 105 +++++++++++++++++++++++++++++++++++++----------
1 files changed, 82 insertions(+), 23 deletions(-)
diff --git a/site/content/api.mdown b/site/content/api.mdown
index 6fbed21..39e334a 100644
--- a/site/content/api.mdown
+++ b/site/content/api.mdown
@@ -443,10 +443,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:
@@ -787,12 +787,17 @@ 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
-newly created ***image***:
+ 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-url-encoded; for example the operation:
+ POST api/images?instance_id=20109341&name=customisedserver&
+ description=jsmith%20customised%20web%20server%20July%2021%202011&format=xml
+will achieve the same results as the example shown below that uses a multipart/form-data
+content-type. The Deltacloud server will respond to a successful operation with
+**HTTP 201 Created** and provide details of the newly created ***image***:
`Example request:`
@@ -819,7 +824,6 @@ newly created ***image***:
jsmith customised web server July 21 2011
------------------------------ba9acb193034--
-
`Server response:`
HTTP/1.1 201 Created
@@ -1372,6 +1376,16 @@ public and private addresses are blank in the server response, as these have not
assigned by the cloud provider. Subsequent requests for the ***instance*** details
will provide these values.
+In the 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. For clarity, the operation:
+
+ http://localhost:3001/api/instances?image_id=ami-f51aff9c&keyname=eftah&
+ realm_id=us-east-1c&hwp_id=c1.medium&firewalls1=default&firewalls2=testformat=xml
+
+will produce the same results as the example below that instead specifies parameters as
+multipart/form-data.
+
<a name=create_instance_ec2>.
`Client request: (AWS EC2)`
@@ -1609,6 +1623,15 @@ operation as shown in the example below. The client should save the private key
***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 whilst the example client request shown below specifies the required
+*name* parameter as multipart/form-data, a client may also legitimately
+specify the same using the application/x-www-form-urlencoded content type.
+Thus, the operation:
+
+ POST http://localhost:3001/api/keys?name=jsmith_new_key&format=xml
+
+is equivalent to the example shown below that uses multipart/form-data.
+
<a name=key_create>.
`Example request:`
@@ -1841,7 +1864,14 @@ Retrieve details of a single specified ***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***:
+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. Thus the operation:
+
+ POST http://localhost:3001/api/firewalls?name=Devel_Group&
+ description=Access%20for%20all%20development%20machines&format=xml
+
+is equivalent to the client example below that instead specifies parameters as form-data.
`Example request:`
@@ -1949,7 +1979,15 @@ Source ***firewalls*** are also specified sequentially but the *owner_id* of the
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***:
+details of the affected ***firewall***. The example client request below specifies the required
+parameters as multipart/form-data. However the following operation:
+
+ POST /api/firewalls/default/rules?protocol=tcp&port_from=22&port_to=22&
+ group1=devel_group&group2=outside&group1owner=393485797142&group2owner=393485797142&
+ ip_address1=192.168.1.1/24&ip_address2=65.128.31.27/32&format=xml
+
+where parameters are instead specified as application/x-www-form-urlencoded is also
+accepted and processed by the Deltacloud server in the same way.
`Example request:`
@@ -2180,8 +2218,10 @@ succesful operation.
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:
-
+produce a **HTTP 202 Accepted** response. The example client request below specifies the required
+ *instance_id* parameter using multipart/form-data however this can also legitimately be specified
+using the application/x-www-form-urlencoded content type
+(i.e., **POST /api/addresses/:id/associate?instance_id=1234&format=xml**).
`Example request:`
@@ -2367,7 +2407,10 @@ This operation creates a new ***load_balancer***. Clients must provide the ***lo
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***.
+***load_balancer***. As with other operations in the Deltacloud API, parameters may be specified
+by a requesting client using multipart/form-data (as shown below), or in the operation URL itself as
+application/x-www-form-urlencoded data (i.e., **POST
+/api/load_balances?name=webtraffic-balancer&realm_id=us-east-1c&** ... etc).
`Example request:`
@@ -2456,7 +2499,10 @@ server will respond with **HTTP 204 No Content** for 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:
+with a **HTTP 204 No Content** after a succesful operation. The Deltacloud server will accept
+client request parameters encoded as multipart/form-data (as in the example below) or
+alternatively as application/x-www-form-urlencoded data
+(e.g. **POST /api/load_balancers/secure-site-balancer/register?instance_id=i-4f06b52e&format=xml**).
`Example request:`
@@ -2483,7 +2529,9 @@ 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***:
+client must supply the **instance_id** parameter to identify the ***instance***, either as
+multipart/form-data (as shown below) or as application/x-www-form-urlencoded data
+(e.g. **POST /api/load_balancers/secure-site-balancer/unregister?instance_id=i-4f06b52e&format=xml**).
`Example request:`
@@ -2619,7 +2667,10 @@ Gigabytes, is also optional and will default to 1 Gigabyte. Finally clients may
**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***:
+created ***storage_volume***. As with the other **POST** operations in the Deltacloud API, clients
+may choose to specify operation parameters as multipart/form-data (as in the example below) or
+as application/x-www-form-urlencoded data (e.g.,
+**POST /api/storage_volumes?capacity=10&realm_id=us-east-1c&format=xml**).
`Example request:`
@@ -2716,7 +2767,10 @@ specify the **instance_id** and the **device** as parameters. The **device** par
***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).
+processing has not yet been completed (hence the **202** status code). Clients may specify the required
+parameters as multipart/form-data (as shown below) or alternatively as
+application/x-www-form-urlencoded data (e.g.,
+**POST /api/storage_volumes/vol-0bc0de60/attach?instance_id=i-b100b3d0&device=/dev/sdi&format=xml**).
`Example request:`
@@ -2894,7 +2948,9 @@ Get all details for a specified ***storage snapshot***, as shown below:
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***:
+newly created ***storage_snapshot***. Clients may specify operation parameters as
+multipart/form-data (as illustrated below), or as application/x-www-form-urlencoded data (e.g.,
+**POST /api/storage_snapshots?volume_id=vol-99fbe5f2&format=xml**).
`Example request:`
@@ -3035,13 +3091,16 @@ 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 in the example below the operation parameters
+are specified as multipart/form-data. However, clients may choose to specify parameters
+using application/x-www-form-urlencoded data (e.g.,
+**POST /api/buckets?name=mybucketeurope&location=EU&format=xml**).
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
--
1.7.3.4
Re: Clarify API Docs on use of multipart/form-data
Posted by David Lutterkort <lu...@redhat.com>.
On Mon, 2011-08-22 at 16:40 +0300, marios@redhat.com wrote:
> Deltacloud API accepts request parameters for POST operations as either
> multipart/form-data or application/x-www-form-urlencoded. Current API
> Docs show all examples with multipart/form-data. This patch clarifies
> that urlencoded parameters can also be used for POST operations,
Looks good - I would go even one step further, and remove the examples
for multipart/form-data whereever application/x-www-form-urlencoded is
permissible; multipart/form-data is not very pleasant reading.
David