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