From: marios <[email protected]>
Signed-off-by: marios <[email protected]> --- site/content/api2.mdown | 1005 +++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 1005 insertions(+), 0 deletions(-) create mode 100644 site/content/api2.mdown diff --git a/site/content/api2.mdown b/site/content/api2.mdown new file mode 100644 index 0000000..751fc95 --- /dev/null +++ b/site/content/api2.mdown @@ -0,0 +1,1005 @@ +--- +title: Deltacloud - Documentation - REST API and Developer Guide +area: documentation +extension: html +filter: + - markdown + - outline +--- + +[basic-relationships]: styles/basic-relationships.png + +# Apache Deltacloud API + +<a name=toc> + +<toc numbering="off" toc_style="ul" toc_range='h2-h4' /> + +* * * + +## 1. Introduction + +Apache Deltacloud is a REST-based (HATEOAS) cloud abstraction API, that enables management of resources in different IaaS clouds using a single API. A series of back-end drivers 'speak' each cloud provider's native API and the Deltacloud Core Framework provides the basis for implementing drivers as needed for other/new IaaS cloud providers. Apache Deltacloud currently supports: Amazon EC3 and S3, Rackspace Cloud Servers and Cloud Files, Gogrid Cloud Servers, Terremark Vcloud Express, Rimuhosting VPS, Red Hat Enterprise Virtualisation (rhev-m), Microsoft Azure (currently Blob storage only), Opennebula, Eucalyptus (including Walrus storage service), IBM Smart Business Cloud and VMware vSphere. + +The Apache Deltacloud project empowers its users in avoiding lockin to any single cloud provider. Deltacloud provides an API abstraction that can be implemented as a wrapper around a large number of clouds, freeing users of cloud from dealing with the particulars of each cloud's API. + +* * * + +### 1.1 Collections + +The following terms represent the abstractions used in the Apache Deltacloud API and are introduced here to aid the reader. Each represents an entity in the 'back-end' provider cloud such as a running virtual server or a server image. It should be noted that not all clouds support all of the following entity collections. Only the appropriate entity collections are exposed for a given back-end driver (e.g. the Microsoft Azure driver currently exposes only the 'Buckets' collection). + +##### Realms + +A distinct organizational unit within the back-end cloud such as a datacenter. A realm may but does not necessarily represent the geographical location of the compute resources being accessed. + +##### Instances + + A realized virtual server, running in a given back-end cloud. These are instantiated from server Images. + +##### Images + +These are templates (virtual machine images) from which Instances are created. Each Image defines the root partition and initial storage for the Instance operating system. + +##### Instance States + +These represent the Instance lifecycle; at any time an Instance will be in one of *start, pending, running, stopped, shutting_down, finished*. + +##### Keys + +These represent credentials used to access a running Instance. These can be of type *key* (e.g., an *RSA* key), or of type *password* (i.e., with *username* and *password* attributes). + +##### Storage_Volume + +This is a virtual storage device that can be attached to an Instance and mounted by the OS therein. + +##### Storage_Snapshot + +These are copies, snapshots of a Storage_Volume at a specified point in time. + +##### Bucket + +A container for data blobs. The organisational unit of a generic *key* ==> *value* based data store (such as Rackspace CloudFiles or Amazon S3). Individual data items, *Blobs*, are exposed as a subcollection under a bucket. + +##### Blob + +A generic binary data item that exists with a specified bucket (an `object' in Amazon S3 and Rackspace CloudFiles). + +##### Address + +Represents an IP addresses. Depending on the back-end cloud provider addresses can be 'public' in which case they represent a unique, globally routable IP address, or 'private' in which case they represent an address routable only within a private network. + +##### Load Balancer + +Allows distribution of ingress network traffic received by a specified IP address to a number of instances. + +<br/> +[Contents](#toc) +<br/> +* * * + +### 1.2 Client Requests + +In keeping with REST, clients make requests through HTTP, with the usual +meanings assigned to the standard HTTP verbs GET, POST, PUT, and DELETE. + +Beyond the generally accepted REST design principles, Apache Deltacloud +follows the guidelines discussed in the Fedora Project [Cloud APIs Rest Style Guide](http://fedoraproject.org/wiki/Cloud_APIs_REST_Style_Guide "Fedora Cloud APIs REST Style Guide"). + +The URL space of the API is structured into collections of resources +(entities, objects). The top level entities used in the Deltacloud API are: +Realms, Images, Instance States, Instances, Keys, Storage Volume, +Storage Snapshots, Blob Storage. + + +<br/> +[Contents](#toc) +<br/> +* * * + +### 1.3 Authentication + +The Deltacloud API server is stateless, and does not keep any information +about the current client. In particular, it does not store the credentials for +the backend cloud it is talking to. Instead, it uses HTTP basic authentication, +and clients have to send the username/password for the backend cloud on every request. + +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. + +<br/> +[Contents](#toc) +<br/> +* * * + +### 1.4 Server responses + +The server can respond to client requests in a variety of formats. The +appropriate response format is determined by HTTP content negotiation. +The primary format is XML, which is the basis for this document. Output is +also available as JSON and, mostly for testing, as HTML. + +In general, list operations, such as `GET /api/realms` will only provide +a brief list of the objects of this resource type; full details can be retrieved +by making a request `GET /api/realms/:id` to the URL of the individual +realm. + +<br/> +[Contents](#toc) +<br/> +* * * + +### 1.5 API conventions + +Any XML element that represents an object, such as an instance has an +href and a id attribute. The href provides the URL at which object-specific +actions can be performed (e.g., a GET to the URL will give details +of the object). The id provides an identifier of the object and this is unique +within its collection (i.e., unique id for each Instance, Image, Realm etc). + +Generally, objects also have a human-readable name; the name is provided in a +`<name/>` child element of the object’s container tag. + +<br/> +[Contents](#toc) +<br/> +* * * + +### 1.6 API stability and evolution + +Future changes to the API will be made in a manner that allows old clients +to work against newer versions of the the API server. + +<br/> +[Contents](#toc) +<br/> +* * * + +### 1.7 Online documentation + +Automatically generated documentation can be accessed on every server running +the Deltacloud Core API service through the URL `http://localhost:3001/api/docs/`. +The documentation is both available in HTML and XML, though the XML format is not +part of this specification, and may change in an incompatible way. + + +<br/> +[Contents](#toc) +<br/> +* * * + +## 2. The API entry point + +Any part of the official API can be reached through the main entry point, +by default http://localhost:3001/api. The entry point list the resources +the server knows about for the current cloud provider; for the Amazon EC2 driver for example, these are: + +* Instances +* Instance states +* Images +* Realms +* Hardware profiles +* Keys +* Buckets +* Storage volumes +* Storage snapshots +* Load Balancers +* Addresses + + +The xml response to a client making a request for the API entry point looks like: + + <api driver='ec2' version='0.3.0'> + <link href='http://localhost:3001/api/storage_volumes' rel='storage_volumes'> + </link> + <link href='http://localhost:3001/api/instances' rel='instances'> + <feature name='user_data'> </feature> + <feature name='authentication_key'> </feature> + <feature name='firewalls'> </feature> + <feature name='instance_count'> </feature> + <feature name='attach_snapshot'> </feature> + </link> + <link href='http://localhost:3001/api/images' rel='images'> + <feature name='owner_id'> </feature> + </link> + <link href='http://localhost:3001/api/drivers' rel='drivers'> </link> + <link href='http://localhost:3001/api/buckets' rel='buckets'> + <feature name='bucket_location'> </feature> + </link> + <link href='http://localhost:3001/api/storage_snapshots' rel='storage_snapshots'> + </link> + <link href='http://localhost:3001/api/load_balancers' rel='load_balancers'> + </link> + <link href='http://localhost:3001/api/realms' rel='realms'> </link> + <link href='http://localhost:3001/api/instance_states' rel='instance_states'> + </link> + <link href='http://localhost:3001/api/hardware_profiles' rel='hardware_profiles'> + </link> + <link href='http://localhost:3001/api/firewalls' rel='firewalls'> </link> + <link href='http://localhost:3001/api/keys' rel='keys'> </link> + <link href='http://localhost:3001/api/addresses' rel='addresses'> </link> + </api> + +Specific implementations for the Apache Deltacloud API may not support all resource +types defined by this API. For example, a Deltacloud instance pointing at a storage-only +service will not expose compute resources like instances and hardware profiles. + + +<br/> +[Contents](#toc) +<br/> +* * * + +### 2.1 Features + +The Apache Deltacloud API defines the standard behavior and semantics +for each of the resource types as a baseline for any API implementation; it +is often desirable to enhance standard API behavior with specific features. +The API also defines all the features that can be supported by an API +implementation - each of them has a fixed, predefined meaning. As an +example, the feature user-name indicates that a user-specified name can be +assigned to an instance when it is created. Features are advertised in the +top-level entry point as illustrated below: + + <api driver='mock' version='0.3.0'> + ... + <link href='http://localhost:3001/api/instances' rel='instances'> + <feature name='hardware_profiles'></feature> + <feature name='user_name'></feature> + <feature name='authentication_key'></feature> + </link> + ... + </api> + +<br/> +[Contents](#toc) +<br/> +* * * + +## 3. Compute Resources + +The compute resources are ***instances, instance states, images, realms, hardware profiles, +firewalls, load balancers, addresses*** and ***keys***. + + +### 3.1 Realms + +A ***realm*** represents a boundary containing resources, such as a data +center. The exact definition of a ***realm*** is left to the cloud provider. +In some cases, a ***realm*** may represent different datacenters, different continents, +or different pools of resources within a single datacenter. A cloud provider may +insist that resources must all exist within a single ***realm*** in order to cooperate. +For instance, storage volumes may only be allowed to be mounted to instances within +the same ***realm***. Generally speaking, going from one ***realm*** to another within the same +cloud may change many aspects of the cloud, such as SLA’s, pricing terms, etc. + +#### `GET /api/realms` + +List all realms. Can be filtered by adding a request parameter ***architecture*** +to the realms that support a specific ***architecture*** such as ***i386***. + +#### `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***, as shown below: + + <realms> + <realm href='http://localhost:3001/api/realms/us' id='us'> + <name>United States</name> + <state>AVAILABLE</state> + <limit></limit> + </realm> + </realms> + +<br/> +[Contents](#toc) +<br/> +* * * + +### 3.2 Hardware Profiles + +A ***hardware profile*** describes the sizing of a virtual machine in a cloud and +prescribes details such as how many virtual CPUs, how much memory or +how much local storage an instance might have. + Since clouds differ sharply in how virtual machine sizing is represented +and influenced, hardware profiles provide a generic mechanism to express sizing +constraints. For each dimension (amount of memory etc.), the hardware +profile can express one of the following: + +1. Size is fixed in this dimension, e.g. instances all have 2GB of memory, *or* +2. Size can be varied freely within some range, e.g. instances can have + from 1GB to 4GB of memory, *or* +3. Size can be chosen from a predefined set of values, an enumeration, + e.g., instances can have 512 MB, 1 GB or 4GB of memory. + +When creating a new ***instance***, a client must specify the ***hardware profile*** +on which the ***instance*** is based. Optionally a client can also specify values for +the variable dimensions of the given hardware profile (otherwise the defaults +specified within each hardware profile are used). + +#### `GET /api/hardware_profiles` + +Produce a list if all ***hardware profiles*** availaible with this cloud. + +#### `GET /api/hardware profiles/:id` + +The attributes of a ***hardware profile*** consist of a human-readable ***name*** and a +list of ***<property/>*** elements. Each property defines possible values along a +sizing dimension. In the example below, the large hardware profile defines +instances with exactly 2 virtual CPUs, memory from between 2GB and 4GB +and local storage that can either be 850MB or 1GB. The default value for +each dimension is indicated by the value attribute on the property element. + +In addition to the sizing constraints, the hardware profile also lists which +parameters can be used in instance operations to change the value of a +property. In the example shown below, only values for the instance +create operation can be changed: + + <hardware_profile href="..." id="large"> + <name>Large profile</name> + <property kind="fixed" name="cpu" unit="count" value="2"/> + + <property kind="range" name="memory" unit="MB" value="10240"> + <param href="/api/instances" method="post" name="hwp_memory" operation="create"/> + <range first="2048" last="4096"/> + </property> + + <property kind="enum" name="storage" unit="MB" value="850"> + <param href="/api/instances" method="post" name="hwp_storage" operation="create"/> + <enum> + <entry value="850"/> + <entry value="1024"/> + </enum> + </property> + + <property kind="fixed" name="architecture" unit="label" value="x86_64"/> + </hardware_profile> + +<br/> +[Contents](#toc) +<br/> +* * * + +### 3.3 Images + +***Images*** are ***used to launch ***instances***. An ***image*** has human-readable ***name*** +and ***description*** attributes as well as an ***architecture***. Each ***image*** represents +a virtual machine image in the back-end cloud, containing the root +partition and initial storage for an instance operating system. + +#### `GET /api/images` + +Return a list of all ***images*** available in the back-end cloud. + +#### `GET /api/images/:id` + +Describe on ***image*** in detail. The ***architecture*** element indicates what +CPU architecture this image expects. It can be either ***x86 64*** for Intel- +based 64 bit processors, and ***i386*** for Intel-compatible 32 bit processors. +The XML description of the image is as shown below: + + <image href="/api/images/img1" id="img1"> + <name>Fedora 10</name> + <owner_id>fedoraproject</owner_id> + <description>Fedora 10</description> + <architecture>x86_64</architecture> + </image> + +<br/> +[Contents](#toc) +<br/> +* * * + +### 3.4 Instance States + +Each cloud defines a slightly different lifecycle model for ***instances***. In some +clouds, ***instances*** start running immediately after creation, in others, they +enter a pending state and they need to be explicitly started to become +running. +These differences between clouds are modelled by expressing the lifecycle +of an instance as a finite state machine and capturing this in a ***instance states*** +entity. The start state of the automaton is start and its final state is +finished. The API defines the following states for an ***instance***, as in Table +1. +The actions (state transitions) possible for an ***instance*** are as shown in +Table 2. The precise actions that can be performed on a specific ***instance*** are +expressed as part of the details for that ***instance***. + +#####Instance states and their meanings: + + State Meaning + ----- ------- + start Instances are in this state before they are created + -- + pending Creation of the instance has been requested and is in progress + -- + running The instance is running + -- + shutting-down A shutdown has been requested for the instance and is in progress + -- + stopped The instance is stopped + -- + finished All resources for this instance have now been freed + +#####Instance actions and their meanings: + + Action Meaning + ------ ------- + start Start the instance + -- + stop Stop (and for some providers, Shutdown) the instance + -- + reboot Reboot the instance + -- + destroy Stop the instance and completely destroy it + + +#### `GET /api/instance_states` + +The ***instance_states*** entity defines the transitions possible between the various + states of an ***instance***, and these are back-end cloud specific. In effect +***instance_states*** defines the finite state machine for ***instances*** from the given +cloud. The XML representation of the instance_state entity is: + + <states> + <state name="start"> + <transition auto="true" to="pending"/> + </state> + + <state name="pending"> + <transition auto="true" to="running"/> + <transition action="stop" to="stopping"/> + <transition auto="true" to="stopped"/> + </state> + + <state name="running"> + <transition action="reboot" to="running"/> + <transition action="stop" to="stopping"/> + </state> + + <state name="stopping"> + </state> + + ... + + </states> + +<br/> +[Contents](#toc) +<br/> +* * * + +### 3.5 Instances + +An ***instance*** represents the focus of all cloud compute activity: a running +virtual machine. An ***instance*** is created from an ***image***, with a specified +***hardware profile*** and in a given ***realm***. Besides these attributes, +each ***instance*** also has a human readable name, an owner id, a state, +public addresses and private addresses (IP address). Each +***instance*** also has an actions attribute (which will depend on +current state) as well as a key. + +#### `GET /api/instances` + +Produce a listing of all current ***Instances*** in the given cloud (belonging to +the specified account). + +#### `GET /api/instances/:id` +Get the details for a specific Instance. The XML returned by the server is +as shown here: + + <instance href="http://localhost:3001/api/instances/i-6109820b"; id="i-6109820b"> + <name>ami-73f2171a</name> + <owner_id>123456789012</owner_id> + <image href="http://localhost:3001/api/images/ami-73f2171a"; id="ami-73f2171a"/> + <realm href="http://localhost:3001/api/realms/us-east-1a"; id="us-east-1a"/> + <state>PENDING</state> + <hardware_profile href="http://localhost:3001/api/hardware_profiles/m1.small"; id="m1.small"> + </hardware_profile> + <actions> + <link href="http://localhost:3001/api/instances/i-6109820b/stop"; method="post" rel="stop"/> + </actions> + <launch_time>2010-08-11T13:13:10.000Z</launch_time> + <public_addresses> + <address/> + </public_addresses> + <private_addresses> + <address/> + </private_addresses> + <authentication type="key"> + <login> + <keyname>eftah</keyname> + </login> + </authentication> + </instance> + +#### `POST /api/instances/:id/:action` + +The valid actions for an ***instance*** are as specified by the ***instance_states*** entity. +At a given time and depending on the current instance state, the set of +permissible actions is as reported in the response to ***GET /api/instances/:id***. + +#### `POST /api/instances/:create` + +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). The details of the new ***instance*** are returned in response to this +operation. + +<br/> +[Contents](#toc) +<br/> +* * * + +### 3.6 Keys + +A ***key*** captures the credentials required to access an ***Instance***. These could be +reported by the back-end cloud during instance creation, in which case they +are captured from response in a ***key*** of type :password (with :username and +:password attributes). For other cloud providers, credentials are specified +by the client itself. In this case credentials are represented by a ***key*** of type +:key (with :fingerprint and :private key attributes). + +#### `GET /api/keys` + +This gives a listing of all available keys. + +#### `GET /api/keys/:id` + +Get the XML description for a specified key, as shown below: + + <key href="http://localhost:3001/api/keys/eftah"; id="eftah" type="key"> + <actions> + <link href="http://localhost:3001/api/keys/eftah"; method="delete" rel="destroy"/> + </actions> + <fingerprint> + a3:d1:21:81:7b:cd:3e:34:e6:5e:8c:d1:31:1c:d1:3e:a1:e3:c5:42 + </fingerprint> + </key> + +#### `POST /api/keys/:create` + +Some back end cloud providers allow a client to create new credentials for +accessing Instances. The parameters (key attributes) required by this func- +tion will depend on the back-end and are specified in the relevant driver. +At present only the EC2 driver implements a key create method and this +requires the name parameter to be specified to create the EC2 keypair. It +should be noted that the private key attribute of a newly created key is +reported only once, in response to the create operation (and should be +saved at this point). Thereafter, only the fingerprint attribute is displayed, +as shown in the XML response above. This feature will be further implemented as support +is provided by back-end clouds. + +#### `DELETE /api/keys/:id` + +Delete a ***key***, specified by its :id attribute. Note that as with the :create +operation, this feature is currently only available in the Amazon EC2 driver. + +<br/> +[Contents](#toc) +<br/> +* * * + +### 3.7 Firewalls + + +#### `GET /api/firewalls` + +#### `GET /api/firewalls/:firewall` + + + + +<br/> +[Contents](#toc) +<br/> +* * * + + + + +## 4. Storage Resources + +Storage resources are divided into two groups: ***storage volumes*** can be attached +to a running instance (accessible by the instance OS), and *blob storage* +which represents a generic 'key <−−> value' based data store, as implemented +by Rackspace CloudFiles or Amazon S3. ***Storage snapshots*** represent a ***storage volume***, +a backup of which is created at a particular point in time (a snapshot). + +### 4.1 Storage Volumes + +#### `GET /api/storage_volumes` + +List all ***storage volumes***. + +#### `GET /api/storage_volumes/:id` + +Get the details for a specic ***storage volume***, as shown below: + + <storage_volume href="http://localhost:3001/api/storage_volumes/vol-5403443d"; id="vol-5403443d"> + <created>2010-08-11T20:40:11.000Z</created> + <capacity>1</capacity> + <device/> + <state>AVAILABLE</state> + <instance/> + </storage_volume> + +<br/> +[Contents](#toc) +<br/> +* * * + +### 4.2 Storage Snapshots + +#### `GET /api/storage_snapshots` + +List all available ***storage snapshots***. + +#### `GET /api/storage_snapshots/:id` + +Get all details for a specified ***storage snapshot***, as shown below: + + <storage_snapshot href="http://localhost:3001/api/storage_snapshots/snap-201dac4b"; id="snap-201dac4b"> + <created>2010-08-11T20:46:10.000Z</created> + <state>COMPLETED</state> + <storage_volume href="http://localhost:3001/api/storage_volumes/vol-5403443d"; id="vol-5403443d"/> + </storage_snapshot> + +<br/> +[Contents](#toc) +<br/> +* * * + +### 4.3 Blob Storage + +Blob storage represents a generic *key* ==> *value* data store, as implemented by Amazon S3 or Rackspace Cloudfiles. In Deltacloud, the organisational unit of blob storage is a ***Bucket***. Individual data items, ***Blobs*** are exposed as a subcollection under each ***Bucket***. + +A ***bucket*** has a ***name***, a ***size*** (denotes the number of ***blobs*** it contains) and a list of links to each ***blob***. + +A ***blob*** has a ***content_length***, a ***content_type***, a ***last_modified*** timestamp, a structure containing ***user_metadata***, a link to the blob ***content*** and the name of the ***bucket*** in which this ***blob*** exists. + +#### `GET /api/buckets` + +Returns a list of all ***buckets*** belonging to the given cloud provider account. The response from the Deltacloud server includes the *name* and *URI* of each ***bucket*** but not the *size* or the list of ***blobs*** contained within them. These details are available when a client requests (*GET*s) a specific ***bucket***. + +`Example request:` + + GET /api/buckets?format=xml HTTP/1.1 + Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa== + User-Agent: curl/7.20.1 + Host: localhost:3001 + Accept: */* + +`Server response:` + + HTTP/1.1 200 OK + Content-Type: application/xml + Content-Length: 597 + <?xml version='1.0' encoding='utf-8' ?> + <buckets> + <bucket href='http://localhost:3001/api/buckets/mybucket1' id='mybucket1'> + <name>mybucket1</name> + <size></size> + </bucket> + <bucket href='http://localhost:3001/api/buckets/mybucket2' id='mybucket2'> + <name>mybucket2</name> + <size></size> + </bucket> + <bucket href='http://localhost:3001/api/buckets/mybucket3' id='mybucket3'> + <name>mybucket3</name> + <size></size> + </bucket> + <bucket href='http://localhost:3001/api/buckets/mybucket4' id='mybucket4'> + <name>mybucket4</name> + <size></size> + </bucket> + </buckets> + +#### `GET /api/buckets/:id` + +Returns the details of a specific ***bucket***, as shown below. The Deltacloud server response includes the *size* of the ***bucket*** and the URI for each ***blob*** object that it contains. + +`Example request:` + + GET /api/buckets/mybucket1?format=xml HTTP/1.1 + Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa== + User-Agent: curl/7.20.1 + Host: localhost:3001 + Accept: */* + +`Server response:` + + HTTP/1.1 200 OK + Content-Type: application/xml + Content-Length: 534 + <?xml version='1.0' encoding='utf-8' ?> + <bucket href='http://localhost:3001/api/buckets/mybucket1' id='mybucket1'> + <name>mybucket1</name> + <size>4</size> + <blob href='http://localhost:3001/api/buckets/mybucket1/myfile' id='myfile'></blob> + <blob href='http://localhost:3001/api/buckets/mybucket1/an_object' id='an_object'></blob> + <blob href='http://localhost:3001/api/buckets/mybucket1/picture_blob' id='picture_blob'></blob> + <blob href='http://localhost:3001/api/buckets/mybucket1/some_blob id='some_blob'></blob> + </bucket> + + +#### `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 [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). + +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:` + + POST /api/buckets?format=xml HTTP/1.1 + Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa== + User-Agent: curl/7.20.1 + Host: localhost:3001 + Accept: */* + 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-- + +`Server response:` + + HTTP/1.1 201 Created + Location: http://localhost:3001/api/buckets/mybucketeurope + Content-Type: application/xml + Content-Length: 182 + + <?xml version='1.0' encoding='utf-8' ?> + <bucket href='http://localhost:3001/api/buckets/mybucketeurope' id='mybucketeurope'> + <name>mybucketeurope</name> + <size>0</size> + </bucket> + +#### `DELETE /api/buckets/:id` + +Deletes the specified ***bucket***, which must be empty (otherwise the call will fail with an error response). A succesful operation will return ***204 No Content***. + +`Example request:` + + DELETE /api/buckets/mybucketeurope?format=xml HTTP/1.1 + Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa== + User-Agent: curl/7.20.1 (i386-redhat-linux-gnu) + Host: localhost:3001 + Accept: */* + +`Server response:` + + HTTP/1.1 204 No Content + + +#### `GET /api/buckets/:bucket_id/:blob_id` + +Retrieve the details of a specific ***blob***. The ***blob*** content is *not* returned as part of the response but rather a URI is given from which the content may be retrieved as shown below: + +`Example request:` + + GET /api/buckets/mariosbucket1/some_more_blob_woo?format=xml HTTP/1.1 + Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa== + User-Agent: curl/7.20.1 (i386-redhat-linux-gnu) + Host: localhost:3001 + Accept: */* + +`Server response:` + + HTTP/1.1 200 OK + Content-Type: application/xml + Content-Length: 586 + <?xml version='1.0' encoding='utf-8' ?> + <blob href='http://localhost:3001/api/buckets/mariosbucket1/some_more_blob_woo' id='some_more_blob_woo'> + <bucket>mariosbucket1</bucket> + <content_length>86</content_length> + <content_type>text/plain</content_type> + <last_modified>Fri Jan 28 12:23:08 UTC 2011</last_modified> + <user_metadata> + <entry key='v'> + <![CDATA[0.2.0]]> + </entry> + <entry key='test'> + <![CDATA[value]]> + </entry> + </user_metadata> + <content href='http://localhost:3001/api/buckets/mariosbucket1/some_more_blob_woo/content'></content> + </blob> + +#### `GET /api/buckets/:bucket_id/:blob_id/content` + +Retrieve the actual blob content, the location of which is specified in the ***content*** URI returned from the `GET /api/buckets/:bucket_id/:blob_id` call. The content is streamed through the deltacloud server as this is received from the back-end cloud provider, to avoid the creation of a temporary file (especially significant in the case of large ***blobs***). The Deltacloud server sets *Content-Disposition: attachment; filename=blob_name* in the HTTP response headers. + +`Example request:` + + GET /api/buckets/mariosanotherbucketohyeah/Im_a_blob_beholdme/content?format=xml HTTP/1.1 + Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa== + User-Agent: curl/7.20.1 (i386-redhat-linux-gnu) + Host: localhost:3001 + Accept: */* + +`Server response:` + + HTTP/1.1 200 OK + Content-Disposition: attachment; filename=Im_a_blob_beholdme + Content-Type: text/plain + Content-Length: 50 + + <BLOB DATA HERE> + +#### `PUT /api/buckets/:bucket_id/:blob_id` + +Creates a ***blob*** object and sets its content. If the ***blob*** already exists then its data and metadata are overwritten with those specified in this call. The request must specify the *name* of the ***blob*** and the *name* of the ***bucket*** in which the ***blob*** is to be placed, in the call URI. The client must also specify in the HTTP headers the *content_length* of the ***blob*** data and the ***blob*** data itself. Optionally the call may also specify a *content_type* and any number of ***key:value*** pairs of user defined *metadata*. User metadata is defined using 'X-Deltacloud-Blobmeta-' header, e.g. ***X-Deltacloud-Blobmeta-Version:2.1***. + +To eliminate the necessity of creating a local file at the deltacloud server for each ***blob*** created, the deltacloud server starts to stream the blob data to the back-end cloud provider as soon as the request headers are processed. A succesful operation will return the newly created blob object, as shown below: + +`Example request:` + + PUT /api/buckets/mybucket/12Jul2011blob?format=xml HTTP/1.1 + Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa== + Content-Type: text/plain + Content-Length: 128988 + X-Deltacloud-Blobmeta-Version:2.1 + X-Deltacloud-Blobmeta-Author:msa + + ... BLOB DATA ... + +`Server response:` + <?xml version='1.0' encoding='utf-8' ?> + <blob href='http://localhost:3001/api/buckets/mybucket/12Jul2011blob' id='12Jul2011blob'> + <bucket>mybucket</bucket> + <content_length>128988</content_length> + <content_type>text/plain</content_type> + <last_modified>Wed Jul 13 13:27:22 UTC 2011</last_modified> + <user_metadata> + <entry key='author'> + <![CDATA[msa]]> + </entry> + <entry key='version'> + <![CDATA[2.1]]> + </entry> + </user_metadata> + <content href='http://localhost:3001/api/buckets/mybucket/12Jul2011blob/content'> + </content> + </blob> + +#### `POST /api/buckets/:bucket_id` + +The deltacloud server also responds to an alternative `POST` route for creating or 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 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 must set the form field ***meta_params*** to specify the number of metadata key/value pairs. The metadata itself is then specified by the client with fields of the form ***meta_nameN*** and ***meta_valueN*** where *N* is an integer from *1* upto the number specified by the ***meta_params*** field (e.g. ***meta_name1=author***, ***meta_value1=jrd***). + +It should be noted that the `POST` method for creating a blob is *non streaming* - that is, the Deltacloud server will create a temporary file with the blob data, before this is transferred to the backend cloud. Thus, it should only be used for ***blobs*** with a relatively small content-length and in general the `PUT` method should be preferred for larger ***blobs***. This `POST` method is mainly provided for clients that cannot easily invoke a `HTTP PUT` operation (for instance, web browsers) and can be used for creating/updating a ***blob*** through the deltacloud HTML interface (provided for testing purposes). + +`Example request:` + + POST /api/buckets/mybucket?format=xml HTTP/1.1 + Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa== + User-Agent: curl/7.20.1 (i386-redhat-linux-gnu) libcurl/7.20.1 N + Accept: */* + Content-Length: 113582 + Expect: 100-continue + Content-Type: multipart/form-data; boundary=----------------------------517f5f2df858 + + ------------------------------517f5f2df858 + Content-Disposition: form-data; name="blob" + + 12Jul2011blob + ------------------------------517f5f2df858 + Content-Disposition: form-data; name="blob_data"; filename="small.txt" + Content-Type: text/plain + + <THE_BLOB_DATA_HERE> + + ------------------------------517f5f2df858 + Content-Disposition: form-data; name="meta_params" + + 2 + ------------------------------517f5f2df858 + Content-Disposition: form-data; name="meta_name1" + + author + ------------------------------517f5f2df858 + Content-Disposition: form-data; name="meta_value1" + jjs + ------------------------------517f5f2df858 + Content-Disposition: form-data; name="meta_name2" + + version + ------------------------------517f5f2df858 + Content-Disposition: form-data; name="meta_value2" + + 2.2 + ------------------------------517f5f2df858-- + +`Server response:` + + <?xml version='1.0' encoding='utf-8' ?> + <blob href='http://localhost:3001/api/buckets/mybucket/12Jul2011blob' id='12Jul2011blob'> + <bucket>mybucket</bucket> + <content_length>112766</content_length> + <content_type>text/plain</content_type> + <last_modified></last_modified> + <user_metadata> + <entry key='x-amz-meta-author'> + <![CDATA[jjs]]> + </entry> + <entry key='x-amz-meta-version'> + <![CDATA[2.2]]> + </entry> + </user_metadata> + <content href='http://localhost:3001/api/buckets/mybucket/12Jul2011blob/content'> + </content> + </blob> + +#### `DELETE /api/buckets/:bucket_id/:blob_id` + +This call deletes the specified ***blob*** object from the back-end cloud. The names of the ***blob*** and the ***bucket*** in which this exists are specified the in call URI. After a succesful operation the Deltacloud server will respond with a `HTTP 204` (No Content) with no message body. + +`Example request:` + + DELETE /api/buckets/mybucket/12Jul2011blob?format=xml HTTP/1.1 + Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa== + User-Agent: curl/7.20.1 (i386-redhat-linux-gnu) + Host: localhost:3001 + Accept: */* + +`Server response:` + + HTTP/1.1 204 No Content + Connection: close + Server: thin 1.2.11 + + +#### `HEAD /api/buckets/:bucket_id/:blob_id` + +The `HTTP HEAD` operation on a specified ***blob*** URI will return all user defined metadata fields. As per [RFC 2616](http://www.ietf.org/rfc/rfc2616.txt "RFC 2616 HTTP/1.1") this `HEAD` operation does not return a message body. Rather, the ***blob*** user metadata values are returned in the response ***X-Deltacloud-Blobmeta-*** headers (e.g., X-Deltacloud-Blobmeta-version:1.2). + +`Example request:` + + HEAD /api/buckets/mybucket/myblob?format=xml HTTP/1.1 + Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa== + User-Agent: curl/7.20.1 + Host: localhost:3001 + Accept: */* + +`Server response:` + + HTTP/1.1 204 No Content + X-Deltacloud-Blobmeta-version: 1.21 + X-Deltacloud-Blobmeta-author: jrd + +#### `POST /api/buckets/:bucket_id/:blob_id` + +A `POST` operation on the URI of a ***blob*** allows a client to update the user-defined ***blob metadata***. Note that this operation will overwrite all previously set user-metadata values (if any) and replace them with those specified in this call. The client must set the user-defined metadata in the ***X-Deltacloud-Blobmeta-*** headers (e.g., X-Deltacloud-Blobmeta-Model:2012). + +`Example request:` + + POST /api/buckets/mybucket/myblob?format=xml HTTP/1.1 + Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa== + User-Agent: curl/7.20.1 + Host: localhost:3001 + Accept: */*$ + +`Server response:` + + HTTP/1.1 204 No Content + X-Deltacloud-Blobmeta-model: 2012 + X-Deltacloud-Blobmeta-paint: Stannite_Grey + +<br/> +[Contents](#toc) +<br/> +* * * + -- 1.7.3.4
