From: marios <[email protected]>
Signed-off-by: marios <[email protected]> --- 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
