incubator-deltacloud-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mar...@redhat.com
Subject [PATCH] REST API update - WORK IN PROGRESS DO NOT COMMIT
Date Fri, 15 Jul 2011 15:56:32 GMT
From: marios <marios@redhat.com>


Signed-off-by: marios <marios@redhat.com>
---
 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


Mime
View raw message