incubator-deltacloud-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From lut...@apache.org
Subject svn commit: r1154412 [3/3] - in /incubator/deltacloud/trunk/site: content/api.mdown output/api.html
Date Fri, 05 Aug 2011 23:10:32 GMT
Modified: incubator/deltacloud/trunk/site/output/api.html
URL: http://svn.apache.org/viewvc/incubator/deltacloud/trunk/site/output/api.html?rev=1154412&r1=1154411&r2=1154412&view=diff
==============================================================================
--- incubator/deltacloud/trunk/site/output/api.html (original)
+++ incubator/deltacloud/trunk/site/output/api.html Fri Aug  5 23:10:32 2011
@@ -2,7 +2,7 @@
 <html>
   <head>
     <title>
-      Deltacloud - Documentation
+      Deltacloud - Documentation - REST API and Developer Guide
     </title>
     <meta content='' name='keywords' />
     <meta content='' name='description' />
@@ -73,297 +73,1917 @@
     <div id='frontpageHeader'></div>
     <div id='main'>
       <div class='container' id='content-deltacloud'>
-        <h1>Deltacloud API</h1>
+        <h1>Apache Deltacloud API</h1>
+        
+        <p><a name="toc" /></p>
         
         <p><ul>
         <li>
-        <a href="#h1">REST</a>
+        <a href="#h1">1. Introduction</a>
+        <ul>
+        <li>
+        <a href="#h1_1">1.1 Collections</a>
+        </li>
+        <li>
+        <a href="#h1_2">1.2 Client Requests</a>
+        </li>
+        <li>
+        <a href="#h1_3">1.3 Authentication</a>
+        </li>
+        <li>
+        <a href="#h1_4">1.4 Server responses</a>
+        </li>
+        <li>
+        <a href="#h1_5">1.5 API conventions</a>
+        </li>
+        <li>
+        <a href="#h1_6">1.6 API stability and evolution</a>
+        </li>
+        <li>
+        <a href="#h1_7">1.7 Online documentation</a>
+        </li>
+        </ul>
+        </li>
+        <li>
+        <a href="#h2">2. The API entry point</a>
+        <ul>
+        <li>
+        <a href="#h2_1">2.1 Features</a>
+        </li>
+        </ul>
+        </li>
+        <li>
+        <a href="#h3">3. Compute Resources</a>
+        <ul>
+        <li>
+        <a href="#h3_1">3.1 Realms</a>
+        <ul>
+        <li>
+        <a href="#h3_1_1">GET /api/realms</a>
+        </li>
+        <li>
+        <a href="#h3_1_2">GET /api/realms/:id</a>
+        </li>
+        </ul>
+        </li>
+        <li>
+        <a href="#h3_2">3.2 Hardware Profiles</a>
+        <ul>
+        <li>
+        <a href="#h3_2_1">GET /api/hardware_profiles</a>
+        </li>
+        <li>
+        <a href="#h3_2_2">GET /api/hardware profiles/:id</a>
+        </li>
+        </ul>
+        </li>
+        <li>
+        <a href="#h3_3">3.3 Images</a>
+        <ul>
+        <li>
+        <a href="#h3_3_1">GET /api/images</a>
+        </li>
+        <li>
+        <a href="#h3_3_2">GET /api/images/:id</a>
+        </li>
+        <li>
+        <a href="#h3_3_3">POST /api/images</a>
+        </li>
+        <li>
+        <a href="#h3_3_4">DELETE /api/images/:id</a>
+        </li>
+        </ul>
+        </li>
+        <li>
+        <a href="#h3_4">3.4 Instance States</a>
+        <ul>
+        <li>
+        <a href="#h3_4_1">GET /api/instance_states</a>
+        </li>
+        </ul>
+        </li>
+        <li>
+        <a href="#h3_5">3.5 Instances</a>
+        <ul>
+        <li>
+        <a href="#h3_5_1">GET /api/instances</a>
+        </li>
+        <li>
+        <a href="#h3_5_2">GET /api/instances/:id</a>
+        </li>
+        <li>
+        <a href="#h3_5_3">POST /api/instances/:id/:action</a>
+        </li>
+        <li>
+        <a href="#h3_5_4">POST /api/instances</a>
+        </li>
+        </ul>
+        </li>
+        <li>
+        <a href="#h3_6">3.6 Keys</a>
+        <ul>
+        <li>
+        <a href="#h3_6_1">GET /api/keys</a>
+        </li>
+        <li>
+        <a href="#h3_6_2">GET /api/keys/:id</a>
+        </li>
+        <li>
+        <a href="#h3_6_3">POST /api/keys</a>
+        </li>
+        <li>
+        <a href="#h3_6_4">DELETE /api/keys/:id</a>
+        </li>
+        </ul>
+        </li>
+        <li>
+        <a href="#h3_7">3.7 Firewalls</a>
+        <ul>
+        <li>
+        <a href="#h3_7_1">GET /api/firewalls</a>
+        </li>
+        <li>
+        <a href="#h3_7_2">GET /api/firewalls/:id</a>
+        </li>
+        <li>
+        <a href="#h3_7_3">POST /api/firewalls</a>
+        </li>
+        <li>
+        <a href="#h3_7_4">DELETE /api/firewalls/:id</a>
+        </li>
+        <li>
+        <a href="#h3_7_5">POST /api/firewalls/:id/rules</a>
+        </li>
+        <li>
+        <a href="#h3_7_6">DELETE /api/firewalls/:id/:rule_id</a>
+        </li>
+        </ul>
+        </li>
+        <li>
+        <a href="#h3_8">3.8 Addresses</a>
+        <ul>
+        <li>
+        <a href="#h3_8_1">GET /api/addresses</a>
+        </li>
+        <li>
+        <a href="#h3_8_2">GET /api/addresses/:id</a>
+        </li>
+        <li>
+        <a href="#h3_8_3">POST /api/addresses</a>
+        </li>
+        <li>
+        <a href="#h3_8_4">DELETE /api/addresses/:id</a>
+        </li>
+        <li>
+        <a href="#h3_8_5">POST /api/addresses/:id/associate</a>
+        </li>
+        <li>
+        <a href="#h3_8_6">POST /api/addresses/:id/disassociate</a>
+        </li>
+        </ul>
+        </li>
+        <li>
+        <a href="#h3_9">3.9 Load Balancers</a>
+        <ul>
+        <li>
+        <a href="#h3_9_1">GET /api/load_balancers</a>
+        </li>
+        <li>
+        <a href="#h3_9_2">GET /api/load_balancers/:id</a>
+        </li>
+        <li>
+        <a href="#h3_9_3">POST /api/load_balancers</a>
+        </li>
+        <li>
+        <a href="#h3_9_4">DELETE /api/load_balancers/:id</a>
+        </li>
+        <li>
+        <a href="#h3_9_5">POST /api/load_balancers/:id/register</a>
+        </li>
+        <li>
+        <a href="#h3_9_6">POST /api/load_balancers/:id/unregister</a>
+        </li>
+        </ul>
+        </li>
+        </ul>
+        </li>
+        <li>
+        <a href="#h4">4. Storage Resources</a>
+        <ul>
+        <li>
+        <a href="#h4_1">4.1 Storage Volumes</a>
+        <ul>
+        <li>
+        <a href="#h4_1_1">GET /api/storage_volumes</a>
+        </li>
+        <li>
+        <a href="#h4_1_2">GET /api/storage_volumes/:id</a>
+        </li>
+        <li>
+        <a href="#h4_1_3">POST /api/storage_volumes</a>
+        </li>
+        <li>
+        <a href="#h4_1_4">DELETE /api/storage_volumes/:id</a>
+        </li>
+        <li>
+        <a href="#h4_1_5">POST /api/storage_volumes/:id/attach</a>
+        </li>
+        <li>
+        <a href="#h4_1_6">POST /api/storage_volumes/:id/detach</a>
+        </li>
+        </ul>
+        </li>
+        <li>
+        <a href="#h4_2">4.2 Storage Snapshots</a>
+        <ul>
+        <li>
+        <a href="#h4_2_1">GET /api/storage_snapshots</a>
+        </li>
+        <li>
+        <a href="#h4_2_2">GET /api/storage_snapshots/:id</a>
         </li>
         <li>
-        <a href="#h2">Authentication</a>
+        <a href="#h4_2_3">POST /api/storage_snapshots</a>
         </li>
         <li>
-        <a href="#h3">Primary Entry Point</a>
+        <a href="#h4_2_4">DELETE /api/storage_snapshots/:id</a>
+        </li>
+        </ul>
         </li>
         <li>
-        <a href="#h4">Resources</a>
+        <a href="#h4_3">4.3 Blob Storage</a>
         <ul>
         <li>
-        <a href="#h4_1">Hardware Profiles</a>
+        <a href="#h4_3_1">GET /api/buckets</a>
+        </li>
+        <li>
+        <a href="#h4_3_2">GET /api/buckets/:id</a>
+        </li>
+        <li>
+        <a href="#h4_3_3">POST /api/buckets</a>
+        </li>
+        <li>
+        <a href="#h4_3_4">DELETE /api/buckets/:id</a>
+        </li>
+        <li>
+        <a href="#h4_3_5">GET /api/buckets/:bucket_id/:blob_id</a>
+        </li>
+        <li>
+        <a href="#h4_3_6">GET /api/buckets/:bucket_id/:blob_id/content</a>
+        </li>
+        <li>
+        <a href="#h4_3_7">PUT /api/buckets/:bucket_id/:blob_id</a>
+        </li>
+        <li>
+        <a href="#h4_3_8">POST /api/buckets/:bucket_id</a>
         </li>
         <li>
-        <a href="#h4_2">Realms</a>
+        <a href="#h4_3_9">DELETE /api/buckets/:bucket_id/:blob_id</a>
         </li>
         <li>
-        <a href="#h4_3">Images</a>
+        <a href="#h4_3_10">HEAD /api/buckets/:bucket_id/:blob_id</a>
         </li>
         <li>
-        <a href="#h4_4">Instances</a>
+        <a href="#h4_3_11">POST /api/buckets/:bucket_id/:blob_id</a>
         </li>
-        </ul></li></ul></p>
+        </ul></li></ul></li></ul></p>
         
-        <p>The Deltacloud API is built as a service-based REST API. You do not
-        directly link a Deltacloud library into your program to use it.
-        Instead, a client speaks the Deltacloud API over HTTP to a server
-        which implements the REST interface.</p>
+        <hr />
         
-        <p>Since cloud providers use their own APIs instead of the Deltacloud
-        API, we provide a translation layer that makes it possible to use
-        Deltacloud with these providers.</p>
+        <h2 id="h1">1. Introduction</h2>
         
-        <h2 id="h1">REST</h2>
+        <p>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 many back-end cloud providers,
+         as listed in <a href="./drivers.html">Drivers</a>.</p>
         
-        <p>The Deltacloud API is a <a href="http://en.wikipedia.org/wiki/Representational_State_Transfer">RESTful API</a>, using HATEOAS architectural
-        style. The API requires no client-side URL construction. Access is
-        based entirely off a single entry-point resource. This allows other
-        implementors to structure their URL space however they like.</p>
+        <p>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.</p>
         
-        <p>Additionally, the Deltacloud API uses <em>content negotiation</em> to
-        determine the format of the returned representation. As of the current
-        revision, the only required representation is XML. Clients wishing to
-        receive XML representations must specify the HTTP <code>Accept</code> header as
-        <code>application/xml</code>.</p>
+        <hr />
         
-        <h2 id="h2">Authentication</h2>
+        <h3 id="h1_1">1.1 Collections</h3>
         
-        <p>The Deltacloud API uses HTTP authentication methods for authenticating
-        a given client. There is no explicit <em>login</em> action required. If
-        authentication is required, an HTTP status of 401 will be returned to
-        challenge for credentials.</p>
+        <p>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).</p>
         
-        <h2 id="h3">Primary Entry Point</h2>
+        <h5>Realms</h5>
         
-        <p>Any Deltacloud implementor <em>must</em> provide exactly one well-known URL
-        as an entry-point. For example, <code>http://fancycloudprovider.com/api</code>.</p>
+        <p>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.</p>
         
-        <p>The result of this entry-point is a set of entry-points into other
-        collections, such as <em>images</em>, <em>instances</em>, <em>hardware profiles</em> and
-        <em>realms</em>, among others.</p>
+        <h5>Instances</h5>
         
-        <p>Each collection is defined by a <code>&lt;link&gt;</code> tag with an <code>href</code> attribute
-        which includes the fully-qualified URL to the collection (which <em>may</em>
-        exist on different servers) and a <code>rel</code> attribute to denote which
-        collection is being specified.</p>
+        <p> A realized virtual server, running in a given back-end cloud. These are instantiated
+        from server Images.</p>
         
-        <pre><code>&lt;api driver='ec2' version='1.0'&gt;&#x000A;  &lt;link href='http://fancycloudprovider.com/api/hardware_profiles' rel='hardware_profiles' /&gt;&#x000A;  &lt;link href='http://fancycloudprovider.com/api/instance_states' rel='instance_states' /&gt;&#x000A;  &lt;link href='http://fancycloudprovider.com/api/realms' rel='realms' /&gt;&#x000A;  &lt;link href='http://fancycloudprovider.com/api/images' rel='images' /&gt;&#x000A;  &lt;link href='http://fancycloudprovider.com/api/instances' rel='instances' /&gt;&#x000A;&lt;/api&gt;&#x000A;</code></pre>
+        <h5>Images</h5>
         
-        <h2 id="h4">Resources</h2>
+        <p>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.</p>
         
-        <p>From the primary entry-point, a client may follow the URL provided for
-        a collection to retrieve the resources within that collection. The
-        collection representation will include the full representations of the
-        items within it, along with links to retrieve each item individually.</p>
+        <h5>Instance States</h5>
         
-        <p><img src="styles/basic-relationships.png" alt="Basic relationships" /></p>
+        <p>These represent the Instance lifecycle; at any time an Instance will be in one of
+         <em>start, pending, running, stopped, shutting_down, finished</em>.</p>
         
-        <h3 id="h4_1">Hardware Profiles</h3>
+        <h5>Keys</h5>
         
-        <p>Within a cloud provider a <em>hardware profile</em> represents a
-        configuration of resources upon which a machine may be deployed. A
-        hardware profile defines aspects such as local disk storage, available
-        RAM, and architecture. A future revision of the Deltacloud API will
-        include more aspects, including number and speed of CPUs available.
-        Each provider is free to define as many (or as few) hardware profiles
-        as desired.</p>
+        <p>These represent credentials used to access a running Instance. These can be of type
+        <em>key</em> (e.g., an <em>RSA</em> key), or of type <em>password</em> (i.e., with <em>username</em> and
+        <em>password</em> attributes).</p>
         
-        <pre><code>&lt;hardware_profiles&gt;&#x000A;  &lt;hardware_profile href='http://fancycloudprovider.com/api/hardware_profiles/m1-small' id='m1-small'&gt;&#x000A;    &lt;property kind='fixed' name='storage' unit='GB' value='160' /&gt;&#x000A;    &lt;property kind='fixed' name='architecture' unit='label' value='i386' /&gt;&#x000A;    &lt;property kind='fixed' name='cpu' unit='count' value='1' /&gt;&#x000A;    &lt;property kind='fixed' name='memory' unit='MB' value='1740.8' /&gt;&#x000A;  &lt;/hardware_profile&gt;&#x000A;</code></pre>
+        <h5>Storage_Volume</h5>
         
-        <p>Each <code>&lt;hardware_profile&gt;</code> block shall contain an <code>href</code> attribute providing a
-        URL to manipulate a specific profile, along with property elements for each
-        attribute of the hardware.</p>
+        <p>This is a virtual storage device that can be attached to an Instance and mounted
+        by the OS therein.</p>
         
-        <ul>
-        <li><strong><code>id</code></strong>            is a unique identifier for the profile</li>
-        <li><strong><code>property</code></strong>      describes each of the hardware aspects</li>
-        </ul>
+        <h5>Storage_Snapshot</h5>
         
+        <p>These are copies, snapshots of a Storage_Volume at a specified point in time.</p>
         
-        <p>Properties have the following attributes:</p>
+        <h5>Bucket</h5>
         
-        <ul>
-        <li><strong><code>name</code></strong>          the type of the property: <em>e.g.</em> <code>memory</code> or <code>storage</code></li>
-        <li><strong><code>unit</code></strong>          the units in which the value is specified: <code>MB</code>, <code>GB</code>, <code>count</code> or <code>label</code></li>
-        <li><strong><code>value</code></strong>         the actual value of the property. It depends on the specified unit: <code>1024</code>, <code>2</code> on <code>x86_64</code></li>
-        <li><strong><code>kind</code></strong>          describes the values to chose from.
+        <p>A container for data blobs. The organisational unit of a generic <em>key</em> ==> <em>value</em>
+         based data store (such as Rackspace CloudFiles or Amazon S3). Individual data
+        items, <em>Blobs</em>, are exposed as a subcollection under a bucket.</p>
         
-        <ul>
-        <li><strong><code>fixed</code></strong>         only the value specified in the property is available</li>
-        <li><strong><code>enum</code></strong>          a list of available values is provided</li>
-        <li><strong><code>range</code></strong>         available values are described by a numeric range</li>
-        </ul>
-        </li>
-        </ul>
+        <h5>Blob</h5>
         
+        <p>A generic binary data item that exists with a specified bucket (an `object' in
+         Amazon S3 and Rackspace CloudFiles).</p>
         
-        <p>When the <code>kind</code> is either an <code>enum</code> or a <code>range</code>, there must be two additional elements specified. One
-        that specifies the allowed values and the second with a way of picking a value.</p>
+        <h5>Address</h5>
         
-        <p>In the non-fixed case, the <code>value</code> property attribute specifies the default value.</p>
+        <p>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.</p>
         
-        <pre><code>  &lt;hardware_profile href='http://fancycloudprovider.com/api/hardware_profiles/m1-xlarge' id='m1-xlarge'&gt;&#x000A;    &lt;property kind='enum' name='storage' unit='GB' value='1024'&gt;&#x000A;      &lt;param href='http://fancycloudprovider.com/api/instances' method='post' name='hwp_storage' operation='create' /&gt;&#x000A;      &lt;enum&gt;&#x000A;        &lt;entry value='1024' /&gt;&#x000A;        &lt;entry value='2048' /&gt;&#x000A;        &lt;entry value='4096' /&gt;&#x000A;      &lt;/enum&gt;&#x000A;    &lt;/property&gt;&#x000A;    &lt;property kind='fixed' name='architecture' unit='label' value='x86_64' /&gt;&#x000A;    &lt;property kind='fixed' name='cpu' unit='count' value='4' /&gt;&#x000A;    &lt;property kind='range' name='memory' unit='MB' value='12288'&gt;&#x000A;      &lt;param href='http://fancycloudprovider.com/api/instances' method='post' name='hwp_memory' operation='create' /&gt;&#x000A;      &lt;range first='12288' last='32768' /&gt;&#
 x000A;    &lt;/property&gt;&#x000A;  &lt;/hardware_profile&gt;&#x000A;&lt;/hardware_profiles&gt;&#x000A;</code></pre>
+        <h5>Load Balancer</h5>
         
-        <p>At this time, hardware profile resources are immutable and read-only. In a
-        future revision they may be mutable.</p>
+        <p>Allows distribution of ingress network traffic received by a specified IP address
+        to a number of instances.</p>
         
-        <h3 id="h4_2">Realms</h3>
+        <h5>Firewalls</h5>
         
-        <p>Within a cloud provider a <em>realm</em> represents a boundary containing
-        resources. 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.</p>
+        <p>Represent sets of rules that govern the accessibility of a running instance over
+        the public Internet</p>
         
-        <pre><code>&lt;realms&gt;&#x000A;  &lt;realm href="http://fancycloudprovider.com/api/realms/us" id='us'&gt;&#x000A;    &lt;name&gt;United States&lt;/name&gt;&#x000A;    &lt;state&gt;AVAILABLE&lt;/state&gt;&#x000A;    &lt;limit/&gt;&#x000A;  &lt;/realm&gt;&#x000A;  &lt;realm href="http://fancycloudprovider.com/api/realms/eu" id='eu'&gt;&#x000A;    &lt;name&gt;Europe&lt;/name&gt;&#x000A;    &lt;state&gt;AVAILABLE&lt;/state&gt;&#x000A;    &lt;limit/&gt;&#x000A;  &lt;/realm&gt;&#x000A;&lt;/realms&gt;&#x000A;</code></pre>
+        <br />
         
-        <p>Each <code>&lt;realm&gt;</code> block shall contain an <code>href</code> attribute providing a URL
-        to manipulate a specific realm, along with elements for each attribute
-        of a realm.</p>
         
-        <ul>
-        <li><strong><code>id</code></strong>          A unique identifier for the realm</li>
-        <li><strong><code>name</code></strong>        A short label</li>
-        <li><strong><code>state</code></strong>       Indicator of the current state of a realm
+        <p><a href="#toc">Contents</a></p>
         
-        <ul>
-        <li>AVAILABLE</li>
-        <li>UNAVAILABLE</li>
-        </ul>
-        </li>
-        <li><strong><code>limit</code></strong>       Limits applicable for the <em>current requester</em></li>
-        </ul>
+        <br />
         
         
-        <h3 id="h4_3">Images</h3>
+        <hr />
         
-        <p>An <em>image</em> is a platonic form of a machine. Images are not directly
-        executable, but are a template for creating actual instances of
-        machines.</p>
+        <h3 id="h1_2">1.2 Client Requests</h3>
         
-        <p>The instances collection will return a set of all images available to
-        the current user.</p>
+        <p>In keeping with REST, clients make requests through HTTP, with the usual
+        meanings assigned to the standard HTTP verbs GET, POST, PUT, and DELETE.</p>
         
-        <pre><code>&lt;images&gt;&#x000A;  &lt;image href="http://fancycloudprovider.com/api/images/img1" id='img1'&gt;&#x000A;    &lt;owner_id&gt;fedoraproject&lt;/owner_id&gt;&#x000A;    &lt;name&gt;Fedora 10&lt;/name&gt;&#x000A;    &lt;description&gt;Fedora 10&lt;/description&gt;&#x000A;    &lt;architecture&gt;x86_64&lt;/architecture&gt;&#x000A;  &lt;/image&gt;&#x000A;  &lt;image href="http://fancycloudprovider.com/api/images/img2" id='img2'&gt;&#x000A;    &lt;owner_id&gt;fedoraproject&lt;/owner_id&gt;&#x000A;    &lt;name&gt;Fedora 10&lt;/name&gt;&#x000A;    &lt;description&gt;Fedora 10&lt;/description&gt;&#x000A;    &lt;architecture&gt;i386&lt;/architecture&gt;&#x000A;  &lt;/image&gt;&#x000A;  &lt;image href="http://fancycloudprovider.com/api/images/img3" id='img3'&gt;&#x000A;    &lt;owner_id&gt;ted&lt;/owner_id&gt;&#x000A;    &lt;name&gt;JBoss&lt;/name&gt;&#x000A;    &lt;description&gt;JBoss&lt;/description&gt;&#x000A;    &lt;architecture&gt;i386&lt;/architecture&gt;&#x
 000A;  &lt;/image&gt;&#x000A;&lt;/images&gt;&#x000A;</code></pre>
+        <p>Beyond the generally accepted REST design principles, Apache Deltacloud
+        follows the guidelines discussed in the Fedora Project <a href="http://fedoraproject.org/wiki/Cloud_APIs_REST_Style_Guide" title="Fedora Cloud APIs REST Style Guide">Cloud APIs Rest Style Guide</a>.</p>
         
-        <p>Each <code>&lt;image&gt;</code> block <em>shall</em> contain an <code>href</code> attribute providing a
-        URL to manipulate a specific image, along with elements for each
-        attribute of an image. Each element, including those for optional
-        attributes must be present. Optional attributes may be specified as a
-        element with empty content.</p>
+        <p>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.</p>
         
-        <p>These attributes include</p>
+        <br />
         
-        <ul>
-        <li><strong><code>id</code></strong>            A unique identifier for the image</li>
-        <li><strong><code>owner_id</code></strong>      An opaque identifier which indicates the owner of an image</li>
-        <li><strong><code>name</code></strong>          An <em>optional</em> short label describing the image</li>
-        <li><strong><code>description</code></strong>   An <em>optional</em> description describing the image more fully</li>
-        <li><strong><code>architecture</code></strong>  A description of the machine architecture of the image
-        which may contain values such as:
         
-        <ul>
-        <li><code>i386</code></li>
-        <li><code>x86_64</code></li>
-        </ul>
-        </li>
-        </ul>
+        <p><a href="#toc">Contents</a></p>
         
+        <br />
         
-        <p>At this time, image resources are immutable and read-only.  In a future revision
-        they will be mutable.</p>
         
-        <h3 id="h4_4">Instances</h3>
+        <hr />
         
-        <p>An <em>instance</em> is a concrete machine realized from an <em>image</em>. The
-        images collection may be obtained by following the link from the
-        primary entry-point.</p>
+        <h3 id="h1_3">1.3 Authentication</h3>
         
-        <pre><code>&lt;instances&gt;&#x000A;  &lt;instance href="http://fancycloudprovider.com/api/instances/inst1" id='inst1'&gt;&#x000A;    &lt;owner_id&gt;larry&lt;/owner_id&gt;&#x000A;    &lt;name&gt;Production JBoss Instance&lt;/name&gt;&#x000A;    &lt;image href="http://fancycloudprovider.com/api/images/img3"/&gt;&#x000A;    &lt;hardware_profile href="http://fancycloudprovider.com/api/hardware_profiles/m1-small"/&gt;&#x000A;    &lt;realm href="http://fancycloudprovider.com/api/realms/us"/&gt;&#x000A;&#x000A;    &lt;state&gt;RUNNING&lt;/state&gt;&#x000A;    &lt;actions&gt;&#x000A;      &lt;link rel="reboot" href="http://fancycloudprovider.com/api/instances/inst1/reboot"/&gt;&#x000A;      &lt;link rel="stop" href="http://fancycloudprovider.com/api/instances/inst1/stop"/&gt;&#x000A;    &lt;/actions&gt;&#x000A;    &lt;public_addresses&gt;&#x000A;      &lt;address&gt;inst1.larry.fancycloudprovider.com&lt;/address&gt;&#x000A;    &lt;/public_addresses&gt;&#x000A;&#x000A;    &
 lt;private_addresses&gt;&#x000A;      &lt;address&gt;inst1.larry.internal&lt;/address&gt;&#x000A;    &lt;/private_addresses&gt;&#x000A;  &lt;/instance&gt;&#x000A;&lt;/instances&gt;&#x000A;</code></pre>
+        <p>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.</p>
         
-        <p>Each <code>&lt;instance&gt;</code> block shall contain an href attribute providing a
-        URL to manipulate a specific instance, along with elements for each
-        attribute of an instance. Each element, including those for optional
-        attributes must be present. Optional attributes may be specified as a
-        element with empty content.</p>
+        <p>The specifics of what needs to be sent varies from cloud to cloud; some
+        cloud providers employ a username and password for API access, whilst
+        others use special-purpose API keys. A list of the credentials that a given
+        cloud provider expects for API access is <a href="documentation.html">available here</a></p>
         
-        <p>Simple attributes include</p>
+        <br />
         
-        <ul>
-        <li><strong><code>id</code></strong>           A unique identifier for the instance</li>
-        <li><strong><code>owner_id</code></strong>     An opaque identifier which indicates the owner of an instance</li>
-        <li><strong><code>name</code></strong>         An <em>optional</em> short label describing the instance</li>
-        <li><strong><code>image</code></strong>        Provides a link to the platonic image from which the instance is based</li>
-        <li><strong><code>hardware_profile</code></strong>       Provides a link to the hardware profile in use by the instance</li>
-        <li><strong><code>realm</code></strong>        Provides a link to the realm where the instance is deployed</li>
-        <li><strong><code>state</code></strong>        Indicator of the instance's current state
+        
+        <p><a href="#toc">Contents</a></p>
+        
+        <br />
+        
+        
+        <hr />
+        
+        <h3 id="h1_4">1.4 Server responses</h3>
+        
+        <p>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. Clients can also
+        explicitly request a specific response format by including the
+        'format=' request parameter (e.g., http://deltacloudserver.foo/api?format=xml
+        or http://deltacloudserver.foo/api?format=json).</p>
+        
+        <p>In general and especially for the html inteface, list operations such as
+        <code>GET /api/realms</code> will only provide a list of the objects of this resource type
+        with only brief details; full details can be retrieved by making a request
+        <code>GET /api/realms/:id</code> to the URL of the individual realm.</p>
+        
+        <br />
+        
+        
+        <p><a href="#toc">Contents</a></p>
+        
+        <br />
+        
+        
+        <hr />
+        
+        <h3 id="h1_5">1.5 API conventions</h3>
+        
+        <p>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).</p>
+        
+        <p>Generally, objects also have a human-readable name; the name is provided in a
+        <code>&lt;name/&gt;</code> child element of the object’s container tag.</p>
+        
+        <br />
+        
+        
+        <p><a href="#toc">Contents</a></p>
+        
+        <br />
+        
+        
+        <hr />
+        
+        <h3 id="h1_6">1.6 API stability and evolution</h3>
+        
+        <p>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.</p>
+        
+        <p>The stability guarantees given by the Apache Deltacloud API imply that the
+        following changes may happen in newer versions of the API:</p>
         
         <ul>
-        <li><code>PENDING</code></li>
-        <li><code>STOPPED</code></li>
-        <li><code>RUNNING</code></li>
-        </ul>
-        </li>
+        <li>adding new collections, or supporting new operations on existing collections</li>
+        <li>adding optional parameters to existing operations</li>
+        <li>adding additional attributes and elements to the XML/JSON responses</li>
         </ul>
         
         
-        <p>Multiple-valued attributes include</p>
+        <p>On the other hand, these changes would violate API stability and will therefore
+        not be made:</p>
         
         <ul>
-        <li><strong><code>public_addresses</code></strong>  Publicly routable IP addresses or names for the instance</li>
-        <li><strong><code>private_addresses</code></strong>  Private network IP addresses or names for the instance</li>
+        <li>removing an operation on a collection</li>
+        <li>making an optional parameter for an operation mandatory</li>
+        <li>removing attributes or elements from XML responses</li>
         </ul>
         
         
-        <p>In addition to the abovementioned attributes, each <code>&lt;instance&gt;</code> may contain an
-        <code>&lt;actions&gt;</code> block specifying valid actions for the instance, along with the URL
-        which may be used to perform the action.  Each action is specified by a <code>&lt;link&gt;</code>
-        with an <code>href</code> attribute providing the URL, and a <code>rel</code> attribute providing
-        a key to determine what the action will do.</p>
+        <br />
         
-        <p>Representative actions include</p>
         
-        <ul>
-        <li><code>reboot</code></li>
-        <li><code>start</code></li>
-        <li><code>stop</code></li>
-        </ul>
+        <p><a href="#toc">Contents</a></p>
         
+        <br />
         
-        <p>Not all actions may be valid at all times for all instances. To invoke
-        an action, a client must perform an HTTP <code>POST</code> to the URL indicated.</p>
         
-        <h4>Creating a new Instance</h4>
+        <hr />
         
-        <p>Per usual REST architectural style, new instances are created by
-        issuing an HTTP <code>POST</code> to the instances collection as defined through
-        the primary entry-point URL. Data should be sent in
-        <code>application/x-www-form-urlencoded</code> format.</p>
+        <h3 id="h1_7">1.7 Online documentation</h3>
         
-        <p>To create a new instance, only one parameter is required</p>
+        <p>Automatically generated documentation can be accessed on every server running
+        the Deltacloud Core API service through the URL <code>http://localhost:3001/api/docs/</code>.
+        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.</p>
         
-        <ul>
-        <li><strong><code>image_id</code></strong>   The identifier (not URL) of the image from which to base the instance</li>
-        </ul>
+        <br />
+        
+        
+        <p><a href="#toc">Contents</a></p>
         
+        <br />
         
-        <p>Optional parameters may also be provided</p>
+        
+        <hr />
+        
+        <h2 id="h2">2. The API entry point</h2>
+        
+        <p>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:</p>
         
         <ul>
-        <li><strong><code>realm_id</code></strong>   The realm in which to launch the instance</li>
-        <li><strong><code>hwp_name</code></strong>  The hardware profile upon which to launch the instance</li>
-        <li><strong><code>name</code></strong>       A short label to identify the instance</li>
+        <li>Instances</li>
+        <li>Instance states</li>
+        <li>Images</li>
+        <li>Realms</li>
+        <li>Hardware profiles</li>
+        <li>Keys</li>
+        <li>Buckets</li>
+        <li>Storage volumes</li>
+        <li>Storage snapshots</li>
+        <li>Load Balancers</li>
+        <li>Addresses</li>
+        <li>Firewalls</li>
         </ul>
         
         
-        <p>If <code>realm_id</code> or <code>hwp_name</code> are not specified, the provider <em>must</em>
-        select reasonable defaults. The architecture of the selected harware profile
-        <em>must</em> match the architecture of the specified image.</p>
+        <p><code>Example request:</code></p>
+        
+        <pre><code>GET /api?format=xml HTTP/1.1&#x000A;Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==&#x000A;User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)&#x000A;Host: localhost:3001&#x000A;Accept: */*&#x000A;</code></pre>
+        
+        <p><code>Server response:</code></p>
+        
+        <pre><code>HTTP/1.1 200 OK&#x000A;Content-Type: application/xml&#x000A;Content-Length: 1439&#x000A;&#x000A;&lt;api driver='ec2' version='0.3.0'&gt;&#x000A;  &lt;link href='http://localhost:3001/api/instance_states' rel='instance_states'&gt;&#x000A;  &lt;/link&gt;&#x000A;  &lt;link href='http://localhost:3001/api/drivers' rel='drivers'&gt;&#x000A;  &lt;/link&gt;&#x000A;  &lt;link href='http://localhost:3001/api/addresses' rel='addresses'&gt;&#x000A;  &lt;/link&gt;&#x000A;  &lt;link href='http://localhost:3001/api/hardware_profiles' rel='hardware_profiles'&gt;&#x000A;  &lt;/link&gt;&#x000A;  &lt;link href='http://localhost:3001/api/firewalls' rel='firewalls'&gt;&#x000A;  &lt;/link&gt;&#x000A;  &lt;link href='http://localhost:3001/api/storage_volumes' rel='storage_volumes'&gt;&#x000A;  &lt;/link&gt;&#x000A;  &lt;link href='http://localhost:3001/api/images' rel='images'&gt;&#x000A;    &lt;feature name='owner_id'&gt;&#x000A;    &lt;/feature&gt;&#x000A;  &lt;/link&gt;&#x00
 0A;  &lt;link href='http://localhost:3001/api/realms' rel='realms'&gt;&#x000A;  &lt;/link&gt;&#x000A;  &lt;link href='http://localhost:3001/api/buckets' rel='buckets'&gt;&#x000A;    &lt;feature name='bucket_location'&gt;&#x000A;    &lt;/feature&gt;&#x000A;  &lt;/link&gt;&#x000A;  &lt;link href='http://localhost:3001/api/instances' rel='instances'&gt;&#x000A;    &lt;feature name='user_data'&gt;&#x000A;    &lt;/feature&gt;&#x000A;    &lt;feature name='authentication_key'&gt;&#x000A;    &lt;/feature&gt;&#x000A;    &lt;feature name='firewalls'&gt;&#x000A;    &lt;/feature&gt;&#x000A;    &lt;feature name='instance_count'&gt;&#x000A;    &lt;/feature&gt;&#x000A;    &lt;feature name='attach_snapshot'&gt;&#x000A;    &lt;/feature&gt;&#x000A;  &lt;/link&gt;&#x000A;  &lt;link href='http://localhost:3001/api/storage_snapshots' rel='storage_snapshots'&gt;&#x000A;  &lt;/link&gt;&#x000A;  &lt;link href='http://localhost:3001/api/keys' rel='keys'&gt;&#x000A;  &lt;/link&gt;&#x000A;  &lt;link h
 ref='http://localhost:3001/api/load_balancers' rel='load_balancers'&gt;&#x000A;  &lt;/link&gt;&#x000A;&lt;/api&gt;&#x000A;</code></pre>
+        
+        <p>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.</p>
+        
+        <br />
+        
+        
+        <p><a href="#toc">Contents</a></p>
+        
+        <br />
+        
+        
+        <hr />
+        
+        <h3 id="h2_1">2.1 Features</h3>
+        
+        <p>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:</p>
+        
+        <pre><code>&lt;api driver='mock' version='0.3.0'&gt;&#x000A;  ...&#x000A;  &lt;link href='http://localhost:3001/api/instances' rel='instances'&gt;&#x000A;    &lt;feature name='hardware_profiles'&gt;&lt;/feature&gt;&#x000A;    &lt;feature name='user_name'&gt;&lt;/feature&gt;&#x000A;    &lt;feature name='authentication_key'&gt;&lt;/feature&gt;&#x000A;  &lt;/link&gt;&#x000A;  ...&#x000A;&lt;/api&gt;&#x000A;</code></pre>
+        
+        <p>The following describes the features available to each collection in
+        the Deltacloud API together with a brief description:</p>
+        
+        <pre><code>Feature                 Collection   Operation             Description&#x000A;-------                 ----------   ---------             -----------&#x000A;owner_id                Images       GET /api/images       Allows filtering of the&#x000A;                                                           image list by owner_id&#x000A;--                      --           --                    --&#x000A;user_name               Instances    POST /api/instances   Accept a user-defined name&#x000A;                                                           on instance creation&#x000A;--                      --           --                    --&#x000A;user_data               Instances    POST /api/instances   Provide user-defined data&#x000A;                                                           that is accessible by the&#x000A;                                                           running instance&#x000A;--                      --           --           
          --&#x000A;user_iso                Instances    POST /api/instances   Provide a base64 encoded&#x000A;                                                           gzipped ISO file accessible&#x000A;                                                           as CD-ROM drive by the&#x000A;                                                           running instnace&#x000A;--                      --           --                    --&#x000A;user_files              Instances    POST /api/instances   Accept files that will be&#x000A;                                                           placed into the launched&#x000A;                                                           instance&#x000A;--                      --           --                    --&#x000A;firewalls               Instances    POST /api/instances   Put the instance into one&#x000A;                                                           or more firewalls on launch&#x000A;--                      --     
       --                    --&#x000A;authentication_key      Instances    POST /api/instances   Provide the authentication&#x000A;                                                           key to be used for&#x000A;                                                           accessing the instance&#x000A;--                      --           --                    --&#x000A;authentication_password Instances    POST /api/instances   Provide the password to be&#x000A;                                                           used to access the running&#x000A;                                                           instance&#x000A;--                      --           --                    --&#x000A;instance_count          Instances    POST /api/instances   Specify the number of&#x000A;                                                           instances to launch in&#x000A;                                                           one operation&#x000A;--                      --  
          --                    --&#x000A;attach_snapshot         Instances    POST /api/instances   Attach a storage_snapshot&#x000A;                                                           to an instance as a&#x000A;                                                           storage_volume&#x000A;--                      --           --                    --&#x000A;sandboxing              Instances    POST /api/instances   Launch a instance from&#x000A;                                                           a sandbox image&#x000A;                                                           (Gogrid specific)&#x000A;--                      --           --                    --&#x000A;bucket_location         Buckets      POST /api/buckets     Specify a location that&#x000A;                                                           the bucket should be&#x000A;                                                           created in (e.g.&#x000A;                                    
                        specific cloud-provider&#x000A;                                                           datacenter)&#x000A;</code></pre>
+        
+        <br />
+        
+        
+        <p><a href="#toc">Contents</a></p>
+        
+        <br />
+        
+        
+        <hr />
+        
+        <h2 id="h3">3. Compute Resources</h2>
+        
+        <p>The compute resources are <strong><em>instances, instance states, images, realms, hardware profiles,
+        firewalls, load balancers, addresses</em></strong> and <strong><em>keys</em></strong>.</p>
+        
+        <h3 id="h3_1">3.1 Realms</h3>
+        
+        <p>A <strong><em>realm</em></strong> represents a boundary containing resources, such as a data
+        center. The exact definition of a <strong><em>realm</em></strong> is left to the cloud provider.
+        In some cases, a <strong><em>realm</em></strong> 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 <strong><em>realm</em></strong> in order to cooperate.
+        For instance, storage volumes may only be allowed to be mounted to instances within
+        the same <strong><em>realm</em></strong>. Generally speaking, going from one <strong><em>realm</em></strong> to another within the same
+        cloud may change many aspects of the cloud, such as SLA’s, pricing terms, etc.</p>
+        
+        <h4 id="h3_1_1"><code>GET /api/realms</code></h4>
+        
+        <p>List all realms. Can be filtered by adding a request parameter <strong><em>architecture</em></strong>
+        to the realms that support a specific <strong><em>architecture</em></strong> such as <strong><em>i386</em></strong>. The example
+        below shows the retrieval of all <strong><em>realms</em></strong> for the AWS EC2 driver, which correspond
+        to EC2 "availability zones":</p>
+        
+        <p><code>Example request:</code></p>
+        
+        <pre><code>GET /api/realms?format=xml HTTP/1.1&#x000A;Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==&#x000A;User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)&#x000A;Host: localhost:3001&#x000A;Accept: */*&#x000A;</code></pre>
+        
+        <p><code>Server response:</code></p>
+        
+        <pre><code>HTTP/1.1 200 OK&#x000A;Content-Type: application/xml&#x000A;Content-Length: 639&#x000A;&lt;?xml version='1.0' encoding='utf-8' ?&gt;&#x000A;&lt;realms&gt;&#x000A;  &lt;realm href='http://localhost:3001/api/realms/us-east-1a' id='us-east-1a'&gt;&#x000A;    &lt;name&gt;us-east-1a&lt;/name&gt;&#x000A;    &lt;state&gt;available&lt;/state&gt;&#x000A;  &lt;/realm&gt;&#x000A;  &lt;realm href='http://localhost:3001/api/realms/us-east-1b' id='us-east-1b'&gt;&#x000A;    &lt;name&gt;us-east-1b&lt;/name&gt;&#x000A;    &lt;state&gt;available&lt;/state&gt;&#x000A;  &lt;/realm&gt;&#x000A;  &lt;realm href='http://localhost:3001/api/realms/us-east-1c' id='us-east-1c'&gt;&#x000A;    &lt;name&gt;us-east-1c&lt;/name&gt;&#x000A;    &lt;state&gt;available&lt;/state&gt;&#x000A;  &lt;/realm&gt;&#x000A;  &lt;realm href='http://localhost:3001/api/realms/us-east-1d' id='us-east-1d'&gt;&#x000A;    &lt;name&gt;us-east-1d&lt;/name&gt;&#x000A;    &lt;state&gt;available&lt;/state&gt;&#x0
 00A;  &lt;/realm&gt;&#x000A;&lt;/realms&gt;&#x000A;</code></pre>
+        
+        <h4 id="h3_1_2"><code>GET /api/realms/:id</code></h4>
+        
+        <p>Provide the details of a <strong><em>realm</em></strong>. Currently, these are a <strong><em>name</em></strong>, a  <strong><em>state</em></strong> and a
+         <em><strong>limit</strong> applicable to the current requester. The </em><strong>name</strong><em> is an arbitrary label
+        with no specific meaning in the API. The </em><strong>state</strong><em> can be either </em><strong>AVAILABLE</strong><em>
+         or </em><strong>UNAVAILABLE</strong><em>. The example below shows the </em><strong>realm</strong><em> for the Rackspace driver.
+        Since Rackspace does not currently have a notion of </em><strong>realms</strong><em> the Deltacloud
+        Rackspace driver provides a single </em><strong>realm</strong>* called 'US', signifying that all
+        compute resources for that cloud provider are hosted in the United States:</p>
+        
+        <p><code>Example request:</code></p>
+        
+        <pre><code>GET /api/realms/us?format=xml HTTP/1.1&#x000A;Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==&#x000A;User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)&#x000A;Host: localhost:3002&#x000A;Accept: */*&#x000A;</code></pre>
+        
+        <p><code>Server response:</code></p>
+        
+        <pre><code>HTTP/1.1 200 OK&#x000A;Content-Type: application/xml&#x000A;Content-Length: 182&#x000A;&#x000A;&lt;?xml version='1.0' encoding='utf-8' ?&gt;&#x000A;&lt;realm href='http://localhost:3001/api/realms/us' id='us'&gt;&#x000A;    &lt;name&gt;United States&lt;/name&gt;&#x000A;    &lt;state&gt;AVAILABLE&lt;/state&gt;&#x000A;    &lt;limit&gt;&lt;/limit&gt;&#x000A;&lt;/realm&gt;&#x000A;</code></pre>
+        
+        <br />
+        
+        
+        <p><a href="#toc">Contents</a></p>
+        
+        <br />
+        
+        
+        <hr />
+        
+        <h3 id="h3_2">3.2 Hardware Profiles</h3>
+        
+        <p>A <strong><em>hardware profile</em></strong> 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. The attributes of a <strong><em>hardware profile</em></strong>
+        consist of a human-readable <strong><em>name</em></strong> and a list of <strong><em><property /></em></strong> elements.
+        Each property defines possible values along a sizing dimension.</p>
+        
+        <p>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:</p>
+        
+        <ol>
+        <li>Size is <strong>fixed</strong> in this dimension, e.g. instances all have 2GB of memory, <em>or</em></li>
+        <li>Size can be varied freely within some <strong>range</strong>, e.g. instances can have
+        from 1GB to 4GB of memory, <em>or</em></li>
+        <li>Size can be chosen from a predefined set of values, an <strong>enumeration</strong>,
+        e.g., instances can have 512 MB, 1 GB or 4GB of memory.</li>
+        </ol>
+        
+        
+        <p>When creating a new <strong><em>instance</em></strong>, a client must specify the <strong><em>hardware profile</em></strong>
+        on which the <strong><em>instance</em></strong> is based.</p>
+        
+        <p>In addition to the sizing constraints, a hardware profile may also indicate the
+        parameters (if any) that can be specified by a client in <strong><em>instance</em></strong> operations.
+        These user-defined, variable dimensions are denoted by a <em>&lt;param></em> XML tag within
+        the given property. For instance, the following extract shows the <em>memory</em> dimension
+        for a hardware profile that can be specified in the HTTP POST <em>create</em> operation of the
+        <strong><em>instances</em></strong> collection (i.e., creating a new instance). The given parameter must be
+        specified using the name <em>hwp_memory</em>, its default value is <em>10240</em> but the client may
+        specify a value in the range <em>7680</em> upto <em>15360</em>:</p>
+        
+        <pre><code>...&#x000A;&lt;property kind='range' name='memory' unit='MB' value='10240'&gt;&#x000A;    &lt;param href='http://localhost:3003/api/instances' method='post' name='hwp_memory' operation='create' /&gt;&#x000A;    &lt;range first='7680.0' last='15360' /&gt;&#x000A;&lt;/property&gt;&#x000A;...&#x000A;</code></pre>
+        
+        <h4 id="h3_2_1"><code>GET /api/hardware_profiles</code></h4>
+        
+        <p>Produce a list if all <strong><em>hardware profiles</em></strong> availaible with this cloud. The example
+        below lists the hardware profiles available in the Amazon EC2 cloud. As EC2 provides
+        a set of pre-defined <strong><em>hardware profiles</em></strong>, the properties of each dimension
+        (memory,cpu etc) are of type <em>fixed</em>:</p>
+        
+        <p><code>Example request:</code></p>
+        
+        <pre><code>GET /api/hardware_profiles?format=xml HTTP/1.1&#x000A;Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==&#x000A;User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)&#x000A;Host: localhost:3001&#x000A;Accept: */*&#x000A;</code></pre>
+        
+        <p><code>Server response:</code></p>
+        
+        <pre><code>HTTP/1.1 200 OK&#x000A;Content-Type: application/xml&#x000A;Content-Length: 3896&#x000A;&lt;?xml version='1.0' encoding='utf-8' ?&gt;&#x000A;&lt;hardware_profiles&gt;&#x000A;  &lt;hardware_profile href='http://localhost:3001/api/hardware_profiles/t1.micro' id='t1.micro'&gt;&#x000A;    &lt;name&gt;t1.micro&lt;/name&gt;&#x000A;    &lt;property kind='fixed' name='cpu' unit='count' value='1' /&gt;&#x000A;    &lt;property kind='fixed' name='memory' unit='MB' value='645.12' /&gt;&#x000A;    &lt;property kind='fixed' name='architecture' unit='label' value='i386' /&gt;&#x000A;    &lt;property kind='fixed' name='storage' unit='GB' value='160' /&gt;&#x000A;  &lt;/hardware_profile&gt;&#x000A;  &lt;hardware_profile href='http://localhost:3001/api/hardware_profiles/m1.small' id='m1.small'&gt;&#x000A;    &lt;name&gt;m1.small&lt;/name&gt;&#x000A;    &lt;property kind='fixed' name='cpu' unit='count' value='1' /&gt;&#x000A;    &lt;property kind='fixed' name='memory' unit='
 MB' value='1740.8' /&gt;&#x000A;    &lt;property kind='fixed' name='architecture' unit='label' value='i386' /&gt;&#x000A;    &lt;property kind='fixed' name='storage' unit='GB' value='160' /&gt;&#x000A;  &lt;/hardware_profile&gt;&#x000A;  &lt;hardware_profile href='http://localhost:3001/api/hardware_profiles/m1.large' id='m1.large'&gt;&#x000A;    &lt;name&gt;m1.large&lt;/name&gt;&#x000A;    &lt;property kind='fixed' name='cpu' unit='count' value='4' /&gt;&#x000A;    &lt;property kind='fixed' name='memory' unit='MB' value='7680.0' /&gt;&#x000A;    &lt;property kind='fixed' name='architecture' unit='label' value='x86_64' /&gt;&#x000A;    &lt;property kind='fixed' name='storage' unit='GB' value='850' /&gt;&#x000A;  &lt;/hardware_profile&gt;&#x000A;  &lt;hardware_profile href='http://localhost:3001/api/hardware_profiles/m1.xlarge' id='m1.xlarge'&gt;&#x000A;    &lt;name&gt;m1.xlarge&lt;/name&gt;&#x000A;    &lt;property kind='fixed' name='cpu' unit='count' value='8' /&gt;&#x000A;  
   &lt;property kind='fixed' name='memory' unit='MB' value='15360' /&gt;&#x000A;    &lt;property kind='fixed' name='architecture' unit='label' value='x86_64' /&gt;&#x000A;    &lt;property kind='fixed' name='storage' unit='GB' value='1690' /&gt;&#x000A;  &lt;/hardware_profile&gt;&#x000A;  &lt;hardware_profile href='http://localhost:3001/api/hardware_profiles/c1.medium' id='c1.medium'&gt;&#x000A;    &lt;name&gt;c1.medium&lt;/name&gt;&#x000A;    &lt;property kind='fixed' name='cpu' unit='count' value='5' /&gt;&#x000A;    &lt;property kind='fixed' name='memory' unit='MB' value='1740.8' /&gt;&#x000A;    &lt;property kind='fixed' name='architecture' unit='label' value='i386' /&gt;&#x000A;    &lt;property kind='fixed' name='storage' unit='GB' value='350' /&gt;&#x000A;  &lt;/hardware_profile&gt;&#x000A;  &lt;hardware_profile href='http://localhost:3001/api/hardware_profiles/c1.xlarge' id='c1.xlarge'&gt;&#x000A;    &lt;name&gt;c1.xlarge&lt;/name&gt;&#x000A;    &lt;property kind='fixed
 ' name='cpu' unit='count' value='20' /&gt;&#x000A;    &lt;property kind='fixed' name='memory' unit='MB' value='7168' /&gt;&#x000A;    &lt;property kind='fixed' name='architecture' unit='label' value='x86_64' /&gt;&#x000A;    &lt;property kind='fixed' name='storage' unit='GB' value='1690' /&gt;&#x000A;  &lt;/hardware_profile&gt;&#x000A;  &lt;hardware_profile href='http://localhost:3001/api/hardware_profiles/m2.xlarge' id='m2.xlarge'&gt;&#x000A;    &lt;name&gt;m2.xlarge&lt;/name&gt;&#x000A;    &lt;property kind='fixed' name='cpu' unit='count' value='6.5' /&gt;&#x000A;    &lt;property kind='fixed' name='memory' unit='MB' value='17510.4' /&gt;&#x000A;    &lt;property kind='fixed' name='architecture' unit='label' value='x86_64' /&gt;&#x000A;    &lt;property kind='fixed' name='storage' unit='GB' value='420' /&gt;&#x000A;  &lt;/hardware_profile&gt;&#x000A;  &lt;hardware_profile href='http://localhost:3001/api/hardware_profiles/m2.2xlarge' id='m2.2xlarge'&gt;&#x000A;    &lt;name&gt;
 m2.2xlarge&lt;/name&gt;&#x000A;    &lt;property kind='fixed' name='cpu' unit='count' value='13' /&gt;&#x000A;    &lt;property kind='fixed' name='memory' unit='MB' value='35020.8' /&gt;&#x000A;    &lt;property kind='fixed' name='architecture' unit='label' value='x86_64' /&gt;&#x000A;    &lt;property kind='fixed' name='storage' unit='GB' value='850' /&gt;&#x000A;  &lt;/hardware_profile&gt;&#x000A;  &lt;hardware_profile href='http://localhost:3001/api/hardware_profiles/m2.4xlarge' id='m2.4xlarge'&gt;&#x000A;    &lt;name&gt;m2.4xlarge&lt;/name&gt;&#x000A;    &lt;property kind='fixed' name='cpu' unit='count' value='26' /&gt;&#x000A;    &lt;property kind='fixed' name='memory' unit='MB' value='70041.6' /&gt;&#x000A;    &lt;property kind='fixed' name='architecture' unit='label' value='x86_64' /&gt;&#x000A;    &lt;property kind='fixed' name='storage' unit='GB' value='1690' /&gt;&#x000A;  &lt;/hardware_profile&gt;&#x000A;&lt;/hardware_profiles&gt;&#x000A;</code></pre>
+        
+        <h4 id="h3_2_2"><code>GET /api/hardware profiles/:id</code></h4>
+        
+        <p>This call retrieves the details of a specific <strong><em>hardware profile</em></strong>.
+        The example below shows a request for the <em>m1-large</em> profile of the Deltacloud <em>mock</em> driver.
+         This <strong><em>hardware profile</em></strong> demonstrates the three different types of parameters (i.e.,
+         <em>fixed</em>, <em>range</em>, <em>enum</em>). The example shows that <strong><em>instances</em></strong> launched with this
+         <strong><em>hardware profile</em></strong> will have exactly <em>2</em> virtual CPUs, memory in the range <em>7.5</em> to
+        <em>15GB</em> 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:</p>
+        
+        <p><code>Example request:</code></p>
+        
+        <pre><code>GET /api/hardware_profiles/m1-large?format=xml HTTP/1.1&#x000A;Authorization: Basic bW9ja3VzZXI6bW9ja3Bhc3N3b3Jk&#x000A;User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)&#x000A;Host: localhost:3003&#x000A;Accept: */*&#x000A;</code></pre>
+        
+        <p><code>Server response:</code></p>
+        
+        <pre><code>HTTP/1.1 200 OK&#x000A;Content-Type: application/xml&#x000A;Content-Length: 808&#x000A;&#x000A;&lt;?xml version='1.0' encoding='utf-8' ?&gt;&#x000A;&lt;hardware_profile href='http://localhost:3003/api/hardware_profiles/m1-large' id='m1-large'&gt;&#x000A;  &lt;name&gt;m1-large&lt;/name&gt;&#x000A;  &lt;property kind='fixed' name='cpu' unit='count' value='2' /&gt;&#x000A;  &lt;property kind='range' name='memory' unit='MB' value='10240'&gt;&#x000A;    &lt;param href='http://localhost:3003/api/instances' method='post' name='hwp_memory' operation='create' /&gt;&#x000A;    &lt;range first='7680.0' last='15360' /&gt;&#x000A;  &lt;/property&gt;&#x000A;  &lt;property kind='enum' name='storage' unit='GB' value='850'&gt;&#x000A;    &lt;param href='http://localhost:3003/api/instances' method='post' name='hwp_storage' operation='create' /&gt;&#x000A;    &lt;enum&gt;&#x000A;      &lt;entry value='850' /&gt;&#x000A;      &lt;entry value='1024' /&gt;&#x000A;    &lt;/enum&
 gt;&#x000A;  &lt;/property&gt;&#x000A;  &lt;property kind='fixed' name='architecture' unit='label' value='x86_64' /&gt;&#x000A;&lt;/hardware_profile&gt;&#x000A;</code></pre>
+        
+        <br />
+        
+        
+        <p><a href="#toc">Contents</a></p>
+        
+        <br />
+        
+        
+        <hr />
+        
+        <h3 id="h3_3">3.3 Images</h3>
+        
+        <p><strong><em>Images</em></strong> are used to launch <strong><em>instances</em></strong>. Each <strong><em>image</em></strong> represents
+        a virtual machine image in the back-end cloud, containing the root
+        partition and initial storage for an instance operating system.</p>
+        
+        <p>An <strong><em>image</em></strong> has human-readable <em>name</em> and <em>description</em>, an <em>owner_id</em>
+        that identifies the user account to which the <strong><em>image</em></strong> belongs, as well as
+        an <em>architecture</em> and a <em>state</em>. The <em>architecture</em> attribute refers to whether the
+        <strong><em>image</em></strong> will create an <strong><em>instance</em></strong> with <em>32</em> or <em>64</em> bit processor; the values
+        that the Deltacloud server returns for this attribute are thus <em>i386</em> and <em>x86_64</em> respectively.
+        The <em>state</em> attribute is as reported by the cloud provider and so will vary between back-end clouds.
+        For example AWS EC2 <strong><em>image</em></strong> state can be one of <em>AVAILABLE</em>, <em>PENDING</em> or <em>FAILED</em>
+        whereas Rackspace Cloudservers <strong><em>image</em></strong> state can be one of <em>UNKNOWN</em>, <em>PREPARING</em>,
+         <em>ACTIVE</em>, <em>QUEUED</em> or <em>FAILED</em>. Finally, each <strong><em>image</em></strong> also contains an &lt;actions>
+        attribute that specifies the URI to which a client may issue a <strong>HTTP POST</strong> for creation of
+        an <strong><em>instance</em></strong> from the given <strong><em>image</em></strong>.</p>
+        
+        <h4 id="h3_3_1"><code>GET /api/images</code></h4>
+        
+        <p>Return a list of all <strong><em>images</em></strong> available in the back-end cloud. By default this call will
+        return <strong>all</strong> images that are available to the given user account. Optionally a client
+        may restrict the list of <strong><em>images</em></strong> returned by specifying the <strong>owner_id</strong> or <strong>architecture</strong>
+        parameters in the request (<strong>architecture</strong> is one of <em>x86_64</em> for 64-bit processors or <em>i386</em>
+        for 32-bit processors). The example below restricts the image list to <strong>64-bit</strong> architecture images
+        belonging to <strong>owner_id 023801271342</strong>:</p>
+        
+        <p><code>Example request:</code></p>
+        
+        <pre><code>GET /api/images?owner_id=023801271342&amp;architecture=x86_64&amp;format=xml HTTP/1.1&#x000A;Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==&#x000A;User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)&#x000A;Host: localhost:3001&#x000A;Accept: */*&#x000A;</code></pre>
+        
+        <p><code>Server response:</code></p>
+        
+        <pre><code>HTTP/1.1 200 OK&#x000A;Content-Type: application/xml&#x000A;Content-Length: 1971&#x000A;&#x000A;&lt;?xml version='1.0' encoding='utf-8' ?&gt;&#x000A;&lt;images&gt;&#x000A;  &lt;image href='http://localhost:3001/api/images/ami-eea35787' id='ami-eea35787'&gt;&#x000A;    &lt;name&gt;sles-10-sp3-v1.00.x86_64&lt;/name&gt;&#x000A;    &lt;owner_id&gt;013907871322&lt;/owner_id&gt;&#x000A;    &lt;description&gt;SUSE Linux Enterprise Server 10 Service Pack 3 for x86_64 (v1.00)&lt;/description&gt;&#x000A;    &lt;architecture&gt;x86_64&lt;/architecture&gt;&#x000A;    &lt;state&gt;&lt;/state&gt;&#x000A;    &lt;actions&gt;&#x000A;      &lt;link href='http://localhost:3001/api/instances;image_id=ami-eea35787' method='post' rel='create_instance' /&gt;&#x000A;    &lt;/actions&gt;&#x000A;  &lt;/image&gt;&#x000A;  &lt;image href='http://localhost:3001/api/images/ami-6e649707' id='ami-6e649707'&gt;&#x000A;    &lt;name&gt;sles-11-sp1-hvm-v1.00.x86_64&lt;/name&gt;&#x000A;    &l
 t;owner_id&gt;013907871322&lt;/owner_id&gt;&#x000A;    &lt;description&gt;SUSE Linux Enterprise Server 11 Service Pack 1 for HVM x86_64 (v1.00)&lt;/description&gt;&#x000A;    &lt;architecture&gt;x86_64&lt;/architecture&gt;&#x000A;    &lt;state&gt;&lt;/state&gt;&#x000A;    &lt;actions&gt;&#x000A;      &lt;link href='http://localhost:3001/api/instances;image_id=ami-6e649707' method='post' rel='create_instance' /&gt;&#x000A;    &lt;/actions&gt;&#x000A;  &lt;/image&gt;&#x000A;  &lt;image href='http://localhost:3001/api/images/ami-e4a7558d' id='ami-e4a7558d'&gt;&#x000A;    &lt;name&gt;sles-11-sp1-hvm-v1.01.x86_64&lt;/name&gt;&#x000A;    &lt;owner_id&gt;013907871322&lt;/owner_id&gt;&#x000A;    &lt;description&gt;SUSE Linux Enterprise Server 11 Service Pack 1 for HVM x86_64 (v1.01)&lt;/description&gt;&#x000A;    &lt;architecture&gt;x86_64&lt;/architecture&gt;&#x000A;    &lt;state&gt;&lt;/state&gt;&#x000A;    &lt;actions&gt;&#x000A;      &lt;link href='http://localhost:3001/api/inst
 ances;image_id=ami-e4a7558d' method='post' rel='create_instance' /&gt;&#x000A;    &lt;/actions&gt;&#x000A;  &lt;/image&gt;&#x000A;  &lt;image href='http://localhost:3001/api/images/ami-e4a3578d' id='ami-e4a3578d'&gt;&#x000A;    &lt;name&gt;sles-11-sp1-v1.00.x86_64&lt;/name&gt;&#x000A;    &lt;owner_id&gt;013907871322&lt;/owner_id&gt;&#x000A;    &lt;description&gt;SUSE Linux Enterprise Server 11 Service Pack 1 for x86_64 (v1.00)&lt;/description&gt;&#x000A;    &lt;architecture&gt;x86_64&lt;/architecture&gt;&#x000A;    &lt;state&gt;&lt;/state&gt;&#x000A;    &lt;actions&gt;&#x000A;      &lt;link href='http://localhost:3001/api/instances;image_id=ami-e4a3578d' method='post' rel='create_instance' /&gt;&#x000A;    &lt;/actions&gt;&#x000A;  &lt;/image&gt;&#x000A;&lt;/images&gt;&#x000A;</code></pre>
+        
+        <h4 id="h3_3_2"><code>GET /api/images/:id</code></h4>
+        
+        <p>Retrieve the description of a specific <strong><em>image</em></strong>.</p>
+        
+        <p><code>Example request:</code></p>
+        
+        <pre><code>GET /api/images/14?format=xml HTTP/1.1&#x000A;Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==&#x000A;User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)&#x000A;Host: localhost:3002&#x000A;Accept: */*&#x000A;</code></pre>
+        
+        <p><code>Server response:</code></p>
+        
+        <pre><code>HTTP/1.1 200 OK&#x000A;Content-Type: application/xml&#x000A;Content-Length: 433&#x000A;&#x000A;&lt;?xml version='1.0' encoding='utf-8' ?&gt;&#x000A;&lt;image href='http://localhost:3002/api/images/14' id='14'&gt;&#x000A;  &lt;name&gt;Red Hat Enterprise Linux 5.4&lt;/name&gt;&#x000A;  &lt;owner_id&gt;jsmith&lt;/owner_id&gt;&#x000A;  &lt;description&gt;Red Hat Enterprise Linux 5.4&lt;/description&gt;&#x000A;  &lt;architecture&gt;x86_64&lt;/architecture&gt;&#x000A;  &lt;state&gt;ACTIVE&lt;/state&gt;&#x000A;  &lt;actions&gt;&#x000A;    &lt;link href='http://localhost:3002/api/instances;image_id=14' method='post' rel='create_instance' /&gt;&#x000A;  &lt;/actions&gt;&#x000A;&lt;/image&gt;&#x000A;</code></pre>
+        
+        <h4 id="h3_3_3"><code>POST /api/images</code></h4>
+        
+        <p>Create a new <strong><em>image</em></strong> from an existing, running <strong><em>instance</em></strong>. This operation is not
+        available in all cloud providers and for some cloud providers this operation is not
+        possible for all <strong><em>instances</em></strong>. For example, in the Amazon EC2 cloud, a custom
+        <strong><em>image</em></strong> can be created from EBS backed <strong><em>instances</em></strong> but not from <strong><em>root-store</em></strong>
+        instances. The Deltacloud API provides a mechanism with which clients can determine whether
+        a given <strong><em>instance</em></strong> may be saved as a custom <strong><em>image</em></strong>. For those cases where
+        <strong><em>instance</em></strong> 'snapshot' is possible, the <strong><em>instance</em></strong> XML &lt;actions> list will
+        contain a <strong>create_image</strong> action that defines the URI for a client to use in creating
+        the new image. For example:</p>
+        
+        <pre><code>...&#x000A;&lt;actions&gt;&#x000A;  &lt;link href='http://localhost:3002/api/instances/20109341/reboot' method='post' rel='reboot' /&gt;&#x000A;  &lt;link href='http://localhost:3002/api/instances/20109341/stop' method='post' rel='stop' /&gt;&#x000A;  &lt;link href='http://localhost:3002/api/instances/20109341/run;id=20109341' method='post' rel='run' /&gt;&#x000A;  &lt;link href='http://localhost:3002/api/images;instance_id=20109341' method='post' rel='create_image' /&gt;&#x000A;&lt;/actions&gt;&#x000A;...&#x000A;</code></pre>
+        
+        <p>To create a new <strong><em>image</em></strong> the client must specify the <em>instance_id</em> of the running instance.
+         Optionally, the client may also provide a <em>name</em> and a <em>description</em>. The parameters are
+        specified as multipart/form-data fields in the client POST. The Deltacloud server will
+        respond to a successful operation with <strong>HTTP 201 Created</strong> and provide details of the
+        newly created <strong><em>image</em></strong>:</p>
+        
+        <p><code>Example request:</code></p>
+        
+        <pre><code>POST /api/images?format=xml HTTP/1.1&#x000A;Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==&#x000A;User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)&#x000A;Host: localhost:3002&#x000A;Accept: */*&#x000A;Content-Length: 404&#x000A;Expect: 100-continue&#x000A;Content-Type: multipart/form-data; boundary=----------------------------ba9acb193034&#x000A;&#x000A;------------------------------ba9acb193034&#x000A;Content-Disposition: form-data; name="instance_id"&#x000A;&#x000A;20109341&#x000A;------------------------------ba9acb193034&#x000A;Content-Disposition: form-data; name="name"&#x000A;&#x000A;customisedserver&#x000A;------------------------------ba9acb193034&#x000A;Content-Disposition: form-data; name="description"&#x000A;&#x000A;jsmith customised web server July 21 2011&#x000A;------------------------------ba9acb193034--&#x000A;</code></pre>
+        
+        <p><code>Server response:</code></p>
+        
+        <pre><code>HTTP/1.1 201 Created&#x000A;Content-Type: application/xml&#x000A;Content-Length: 427&#x000A;&#x000A;&lt;?xml version='1.0' encoding='utf-8' ?&gt;&#x000A;&lt;image href='http://localhost:3002/api/images/12346145' id='12346145'&gt;&#x000A;  &lt;name&gt;customisedserver&lt;/name&gt;&#x000A;  &lt;owner_id&gt;mandreou&lt;/owner_id&gt;&#x000A;  &lt;description&gt;customisedserver&lt;/description&gt;&#x000A;  &lt;architecture&gt;x86_64&lt;/architecture&gt;&#x000A;  &lt;state&gt;QUEUED&lt;/state&gt;&#x000A;  &lt;actions&gt;&#x000A;    &lt;link href='http://localhost:3002/api/instances;image_id=12346145' method='post' rel='create_instance' /&gt;&#x000A;  &lt;/actions&gt;&#x000A;&lt;/image&gt;&#x000A;</code></pre>
+        
+        <h4 id="h3_3_4"><code>DELETE /api/images/:id</code></h4>
+        
+        <p>Deletes the specified <strong><em>image</em></strong> from the back-end cloud. The Deltacloud server
+        will return a <strong>HTTP 204 No Content</strong> after a succesful operation:</p>
+        
+        <p><code>Example request:</code></p>
+        
+        <pre><code>DELETE /api/images/12346145?format=xml HTTP/1.1&#x000A;Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==&#x000A;User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)&#x000A;Host: localhost:3002&#x000A;Accept: */*&#x000A;</code></pre>
+        
+        <p><code>Server response:</code></p>
+        
+        <pre><code>HTTP/1.1 204 No Content&#x000A;</code></pre>
+        
+        <br />
+        
+        
+        <p><a href="#toc">Contents</a></p>
+        
+        <br />
+        
+        
+        <hr />
+        
+        <h3 id="h3_4">3.4 Instance States</h3>
+        
+        <p>Each cloud defines a slightly different lifecycle model for <strong><em>instances</em></strong>. In some
+        clouds, <strong><em>instances</em></strong> start running immediately after creation, in others, they
+        enter a pending state and they need to be explicitly started to become
+        running.</p>
+        
+        <p>These differences between clouds are modelled by expressing the lifecycle
+        of an instance as a finite state machine and capturing this in a <strong><em>instance states</em></strong>
+        entity. The start state of the automaton is start and its final state is
+        finished. The API defines the following states for an <strong><em>instance</em></strong>:</p>
+        
+        <h5>Instance states and their meanings:</h5>
+        
+        <pre><code>State             Meaning&#x000A;-----             -------&#x000A;start             Instances are in this state before they are created&#x000A;--&#x000A;pending           Creation of the instance has been requested and is in progress&#x000A;--&#x000A;running           The instance is running&#x000A;--&#x000A;shutting-down     A shutdown has been requested for the instance and is in progress&#x000A;--&#x000A;stopped           The instance is stopped&#x000A;--&#x000A;finished          All resources for this instance have now been freed&#x000A;</code></pre>
+        
+        <p>The actions (state transitions) possible for an <strong><em>instance</em></strong> are as shown below.
+        The precise actions that can be performed on a specific <strong><em>instance</em></strong> are
+        expressed as part of the details for that <strong><em>instance</em></strong>.</p>
+        
+        <h5>Instance actions and their meanings:</h5>
+        
+        <pre><code>Action            Meaning&#x000A;------            -------&#x000A;start             Start the instance&#x000A;--&#x000A;stop              Stop (and for some providers, Shutdown) the instance&#x000A;--&#x000A;reboot            Reboot the instance&#x000A;--&#x000A;destroy           Stop the instance and completely destroy it&#x000A;</code></pre>
+        
+        <h4 id="h3_4_1"><code>GET /api/instance_states</code></h4>
+        
+        <p>This call retrieves the <strong><em>instance_states</em></strong> entity for a back-end cloud. The <strong><em>instance_states</em></strong>
+        entity defines the transitions possible between the various states of an <strong><em>instance</em></strong>,
+        and these are back-end cloud specific. In effect <strong><em>instance_states</em></strong> defines the finite state
+        machine for <strong><em>instances</em></strong> from the given cloud.</p>
+        
+        <p><code>Example request:</code></p>
+        
+        <pre><code>GET /api/instance_states?format=xml HTTP/1.1&#x000A;Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==&#x000A;User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)&#x000A;Host: localhost:3002&#x000A;Accept: */*&#x000A;</code></pre>
+        
+        <p><code>Server response:</code></p>
+        
+        <pre><code>HTTP/1.1 200 OK&#x000A;Content-Type: application/xml&#x000A;Content-Length: 583&#x000A;&#x000A;&lt;states&gt;&#x000A;  &lt;state name='start'&gt;&#x000A;    &lt;transition action='create' to='pending'&gt;&lt;/transition&gt;&#x000A;  &lt;/state&gt;&#x000A;  &lt;state name='pending'&gt;&#x000A;    &lt;transition auto='true' to='running'&gt;&lt;/transition&gt;&#x000A;  &lt;/state&gt;&#x000A;  &lt;state name='running'&gt;&#x000A;    &lt;transition action='reboot' to='running'&gt;&lt;/transition&gt;&#x000A;    &lt;transition action='stop' to='shutting_down'&gt;&lt;/transition&gt;&#x000A;  &lt;/state&gt;&#x000A;  &lt;state name='shutting_down'&gt;&#x000A;    &lt;transition auto='true' to='stopped'&gt;&lt;/transition&gt;&#x000A;  &lt;/state&gt;&#x000A;  &lt;state name='stopped'&gt;&#x000A;    &lt;transition auto='true' to='finish'&gt;&lt;/transition&gt;&#x000A;  &lt;/state&gt;&#x000A;  &lt;state name='finish'&gt;&#x000A;  &lt;/state&gt;&#x000A;&lt;/states&gt;&#x0
 00A;</code></pre>
+        
+        <br />
+        
+        
+        <p><a href="#toc">Contents</a></p>
+        
+        <br />
+        
+        
+        <hr />
+        
+        <h3 id="h3_5">3.5 Instances</h3>
+        
+        <p>An <strong><em>instance</em></strong> represents the focus of all cloud compute activity: a running
+        virtual machine. An <strong><em>instance</em></strong> is created from an <strong><em>image</em></strong>, with a specified
+        <strong><em>hardware profile</em></strong> and in a given <strong><em>realm</em></strong>. Each <strong><em>instance</em></strong> can have a
+        number of other attributes, not all of which are exposed for all back-end cloud
+        providers. The full list of possible <strong><em>instance</em></strong> attributes is:</p>
+        
+        <pre><code>Attribute           Meaning&#x000A;---------           -------&#x000A;owner_id            The id of the cloud provider account that launched the instance&#x000A;--&#x000A;image_id            The id of the image from which the instance was launched&#x000A;--&#x000A;name                A human readable name for the instance given at launch time&#x000A;--&#x000A;realm_id            Realm into which the instance was launced&#x000A;--&#x000A;state               Current state of the instance (e.g., 'running')&#x000A;--&#x000A;actions             Actions that a client may effect on the instance, based on current state.&#x000A;--&#x000A;public_addresses    The globally routable IP address of the instance&#x000A;--&#x000A;private_addresses   The private IP address of the instance, routable within its private network&#x000A;--&#x000A;instance_profile    The specific values of memory, cpu, storage&#x000A;--&#x000A;launch_time         Timestamp at which the instance w
 as launched&#x000A;--&#x000A;keyname             Name of authentication Key, if this method is used for authentication (e.g., EC2)&#x000A;--&#x000A;username            The username for authentication when connecting to the instance&#x000A;--&#x000A;password            The password used together with username above.&#x000A;--&#x000A;firewalls           The firewalls that this instance was launched into (EC2 specific)&#x000A;--&#x000A;</code></pre>
+        
+        <h4 id="h3_5_1"><code>GET /api/instances</code></h4>
+        
+        <p>Produce a listing of all current <strong><em>Instances</em></strong> in the given cloud (belonging to
+        the specified account). The example shown below displays <strong><em>instances</em></strong> in the Amazon EC2 cloud:</p>
+        
+        <p><code>Example request:</code></p>
+        
+        <pre><code>GET /api/instances?format=xml HTTP/1.1&#x000A;Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==&#x000A;User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)&#x000A;Host: localhost:3001&#x000A;Accept: */*&#x000A;</code></pre>
+        
+        <p><code>Client response:</code></p>
+        
+        <pre><code>HTTP/1.1 200 OK&#x000A;Content-Type: application/xml&#x000A;Content-Length: 2790&#x000A;&lt;?xml version='1.0' encoding='utf-8' ?&gt;&#x000A;&lt;instances&gt;&#x000A;  &lt;instance href='http://localhost:3001/api/instances/i-1fbc627e' id='i-1fbc627e'&gt;&#x000A;    &lt;name&gt;ami-f51aff9c&lt;/name&gt;&#x000A;    &lt;owner_id&gt;393485797142&lt;/owner_id&gt;&#x000A;    &lt;image href='http://localhost:3001/api/images/ami-f51aff9c' id='ami-f51aff9c'&gt;&lt;/image&gt;&#x000A;    &lt;realm href='http://localhost:3001/api/realms/us-east-1c' id='us-east-1c'&gt;&lt;/realm&gt;&#x000A;    &lt;state&gt;RUNNING&lt;/state&gt;&#x000A;    &lt;hardware_profile href='http://localhost:3001/api/hardware_profiles/c1.medium' id='c1.medium'&gt;&#x000A;    &lt;/hardware_profile&gt;&#x000A;    &lt;actions&gt;&#x000A;      &lt;link href='http://localhost:3001/api/instances/i-1fbc627e/reboot' method='post' rel='reboot' /&gt;&#x000A;      &lt;link href='http://localhost:3001/api/i
 nstances/i-1fbc627e/stop' method='post' rel='stop' /&gt;&#x000A;      &lt;link href='http://localhost:3001/api/instances/i-1fbc627e/run;id=i-1fbc627e' method='post' rel='run' /&gt;&#x000A;    &lt;/actions&gt;&#x000A;    &lt;launch_time&gt;2011-07-22T11:29:48.000Z&lt;/launch_time&gt;&#x000A;    &lt;public_addresses&gt;&lt;address&gt;ec2-50-16-183-107.compute-1.amazonaws.com&lt;/address&gt;&lt;/public_addresses&gt;&#x000A;    &lt;private_addresses&gt;&lt;address&gt;domU-12-31-39-0F-79-D4.compute-1.internal&lt;/address&gt;&lt;/private_addresses&gt;&#x000A;    &lt;firewalls&gt;&#x000A;      &lt;firewall href='http://localhost:3001/api/firewalls/default' id='default'&gt;&lt;/firewall&gt;&#x000A;    &lt;/firewalls&gt;&#x000A;    &lt;authentication type='key'&gt;&#x000A;      &lt;login&gt;&#x000A;        &lt;keyname&gt;eftah&lt;/keyname&gt;&#x000A;      &lt;/login&gt;&#x000A;    &lt;/authentication&gt;&#x000A;  &lt;/instance&gt;&#x000A;  &lt;instance href='http://localhost:3001/api
 /instances/i-f3ba6492' id='i-f3ba6492'&gt;&#x000A;    &lt;name&gt;ami-2b5fba42&lt;/name&gt;&#x000A;    &lt;owner_id&gt;393485797142&lt;/owner_id&gt;&#x000A;    &lt;image href='http://localhost:3001/api/images/ami-2b5fba42' id='ami-2b5fba42'&gt;&lt;/image&gt;&#x000A;    &lt;realm href='http://localhost:3001/api/realms/us-east-1d' id='us-east-1d'&gt;&lt;/realm&gt;&#x000A;    &lt;state&gt;RUNNING&lt;/state&gt;&#x000A;    &lt;hardware_profile href='http://localhost:3001/api/hardware_profiles/m1.small' id='m1.small'&gt;&#x000A;    &lt;/hardware_profile&gt;&#x000A;    &lt;actions&gt;&#x000A;      &lt;link href='http://localhost:3001/api/instances/i-f3ba6492/reboot' method='post' rel='reboot' /&gt;&#x000A;      &lt;link href='http://localhost:3001/api/instances/i-f3ba6492/stop' method='post' rel='stop' /&gt;&#x000A;      &lt;link href='http://localhost:3001/api/instances/i-f3ba6492/run;id=i-f3ba6492' method='post' rel='run' /&gt;&#x000A;    &lt;/actions&gt;&#x000A;    &lt;launch_ti
 me&gt;2011-07-22T11:32:25.000Z&lt;/launch_time&gt;&#x000A;    &lt;public_addresses&gt;&lt;address&gt;ec2-184-73-78-87.compute-1.amazonaws.com&lt;/address&gt;&lt;/public_addresses&gt;&#x000A;    &lt;private_addresses&gt;&lt;address&gt;ip-10-196-89-221.ec2.internal&lt;/address&gt;&lt;/private_addresses&gt;&#x000A;    &lt;firewalls&gt;&#x000A;      &lt;firewall href='http://localhost:3001/api/firewalls/default' id='default'&gt;&lt;/firewall&gt;&#x000A;      &lt;firewall href='http://localhost:3001/api/firewalls/test' id='test'&gt;&lt;/firewall&gt;&#x000A;    &lt;/firewalls&gt;&#x000A;    &lt;authentication type='key'&gt;&#x000A;      &lt;login&gt;&#x000A;        &lt;keyname&gt;eftah&lt;/keyname&gt;&#x000A;      &lt;/login&gt;&#x000A;    &lt;/authentication&gt;&#x000A;  &lt;/instance&gt;&#x000A;&lt;/instances&gt;&#x000A;</code></pre>
+        
+        <h4 id="h3_5_2"><code>GET /api/instances/:id</code></h4>
+        
+        <p>Get the details for a specific <strong><em>Instance</em></strong>. The example shown below is for an <strong><em>instance</em></strong>
+        launched in the Rackspace Cloudservers cloud. As can be seen, the authentication type used is
+        <strong>password</strong> but the <em>username</em> and <em>password</em> attributes are blank. This is because Rackspace
+        only reports these values once, during instance creation and not for subsequent requests.
+        An example of the response from <strong><em>instance</em></strong> creation can be found under the
+        <a href="#create_instance">POST /api/instances</a> subsection below, showing how the<em>username</em>/<em>password</em>
+        fields are populated.</p>
+        
+        <p><code>Example request:</code></p>
+        
+        <pre><code>GET /api/instances/20112212?format=xml HTTP/1.1&#x000A;Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==&#x000A;User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)&#x000A;Host: localhost:3002&#x000A;Accept: */*&#x000A;</code></pre>
+        
+        <p><code>Server response:</code>
+        <a name="get_instance"> .</a></p>
+        
+        <pre><code>HTTP/1.1 200 OK&#x000A;Content-Type: application/xml&#x000A;Content-Length: 1167&#x000A;&lt;?xml version='1.0' encoding='utf-8' ?&gt;&#x000A;&lt;instance href='http://localhost:3002/api/instances/20112212' id='20112212'&gt;&#x000A;  &lt;name&gt;myserver&lt;/name&gt;&#x000A;  &lt;owner_id&gt;mandreou&lt;/owner_id&gt;&#x000A;  &lt;image href='http://localhost:3002/api/images/53' id='53'&gt;&lt;/image&gt;&#x000A;  &lt;realm href='http://localhost:3002/api/realms/us' id='us'&gt;&lt;/realm&gt;&#x000A;  &lt;state&gt;RUNNING&lt;/state&gt;&#x000A;  &lt;hardware_profile href='http://localhost:3002/api/hardware_profiles/1' id='1'&gt;&#x000A;  &lt;/hardware_profile&gt;&#x000A;  &lt;actions&gt;&#x000A;    &lt;link href='http://localhost:3002/api/instances/20112212/reboot' method='post' rel='reboot' /&gt;&#x000A;    &lt;link href='http://localhost:3002/api/instances/20112212/stop' method='post' rel='stop' /&gt;&#x000A;    &lt;link href='http://localhost:3002/api/instan
 ces/20112212/run;id=20112212' method='post' rel='run' /&gt;&#x000A;    &lt;link href='http://localhost:3002/api/images;instance_id=20112212' method='post' rel='create_image' /&gt;&#x000A;  &lt;/actions&gt;&#x000A;  &lt;public_addresses&gt;&lt;address&gt;50.57.116.72&lt;/address&gt;&lt;/public_addresses&gt;&#x000A;  &lt;private_addresses&gt;&lt;address&gt;10.182.143.64&lt;/address&gt;&lt;/private_addresses&gt;&#x000A;  &lt;authentication type='password'&gt;&#x000A;    &lt;login&gt;&#x000A;      &lt;username&gt;root&lt;/username&gt;&#x000A;      &lt;password&gt;&lt;/password&gt;&#x000A;    &lt;/login&gt;&#x000A;  &lt;/authentication&gt;&#x000A;&lt;/instance&gt;&#x000A;</code></pre>
+        
+        <h4 id="h3_5_3"><code>POST /api/instances/:id/:action</code></h4>
+        
+        <p>The valid actions for an <strong><em>instance</em></strong> are specified by the <strong><em>instance_states</em></strong> entity.
+        The set of permissible actions that a client may effect on an <strong><em>instance</em></strong> at a given time
+        depends on the current <strong><em>instance state</em></strong>. These are as reported by the &lt;actions> attribute
+        in the Deltacloud server response to a <a href="#get_instance">GET /api/instances/:id</a> call. The first
+        example shown below is to <strong>reboot</strong> a currently running instance, followed by a <strong>stop</strong>.</p>
+        
+        <p>Note that after invoking the <strong>stop</strong> operation, the <strong><em>instance</em></strong> state may be reported as <strong>RUNNING</strong>
+        in the Deltacloud server response. This is because it may take some time for the <strong><em>instance</em></strong> state
+         to change in the backend cloud provider (and this will vary between providers). Subsequent requests
+         for either the list of <strong><em>instances</em></strong> or a specific <strong><em>instance</em></strong> will confirm that the action was
+         effected correctly.</p>
+        
+        <p>The Deltacloud server also allows a special 'run-on-instance' action for some cloud provider
+        <strong><em>instances</em></strong>.This enables a client to perform a command on a running <strong><em>instance</em></strong> over
+        <strong>SSH</strong> and the Deltacloud server will return the output of that command to the client.
+         Where available, this is reported as the <strong>run</strong> action in the list of <strong><em>instance</em></strong>
+        actions. The command to be executed on the running <strong><em>instance</em></strong> is specified by the
+        <strong>cmd</strong> parameter, whilst authentication is specified either by the <strong>private_key</strong> parameter
+        for cloud providers that expect key based authentication for connecting to <strong><em>instances</em></strong>
+        or the <strong>password</strong> parameter for those cloud providers that use a <strong>username/password</strong> for
+        authentication. The last examples shown below illustrate the 'run-on-instance' feature for
+        an Amazon EC2 <strong><em>instance</em></strong> and a Rackspace Cloudservers <strong><em>instance</em></strong>. The two examples

[... 976 lines stripped ...]


Mime
View raw message