You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@deltacloud.apache.org by ma...@redhat.com on 2011/07/15 17:56:32 UTC
[PATCH] REST API update - WORK IN PROGRESS DO NOT COMMIT
From: marios <ma...@redhat.com>
Signed-off-by: marios <ma...@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
Re: [PATCH] REST API update - WORK IN PROGRESS DO NOT COMMIT
Posted by David Lutterkort <lu...@redhat.com>.
On Fri, 2011-07-15 at 18:56 +0300, marios@redhat.com wrote:
> From: marios <ma...@redhat.com>
This is great - I really like where this is going.
A have a few nitpicky/editorial comments:
First nitpick: please keep lines to 80 chars or less; there's a ton of
very long lines ...
> +## 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.
Instead of enumerating all the supported backends, just include a link
to http://localhost:4331/drivers.html#h4 - there's a higher likelihood
that we'll keep that page up to date.
> +### 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.
Include a link to http://localhost:4331/documentation.html where we list
what the actual creds are for every cloud.
> +### 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.
We should explain what we mean by API stability. Maybe something like
the following:
The stability guarantees given by the API imply that the
following changes may happen in newer versions of the API:
* adding new collections, or supporting new operations on
existing collections
* adding optional parameters to existing operations
* adding additional attributes and elements to the XML
responses
On the other hand, these changes would violate API stability,
and will therefore not be made
* removing an operation on a collection
* making an optional parameter for an operation mandatory
* removing attributes or elements from XML responses
> +### 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:
We should include a list of all the features (maybe in an appendix, or
right here) and then have individual operations list what features may
apply to them.
The important thing about the list of features is to explain what each
of them means, in particular 'if you see feature hamncheese, you know
that the create instance operation can also make you a ham and cheese
sandwich'
David