Deltacloud API

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.

Of course, at this point in time, no cloud provider natively speaks the Deltacloud API. To accomodate the native APIs used by the various cloud providers, the Deltacloud project also provides a framework and a set of drivers that work with the framework.

By running a framework & driver combination on some host, your application can use the Deltacloud API, and the driver is responsible for translating these calls into each provider's own API.

REST

The Deltacloud API is a RESTful API, 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.

Additionally, the Deltacloud API uses content negotiation 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 Accept header as text/xml.

Authentication

The Deltacloud API uses HTTP authentication methods for authenticating a given client. There is no explicit login action required. If authentication is required, an HTTP status of 401 will be returned to challenge for credentials.

Primary Entry Point

Any Deltacloud implementor must provide exactly one well-known URL as an entry-point. For example, http://fancycloudprovider.com/api.

The result of this entry-point is a set of entry-points into other collections, such as images, instances, flavors and realms, among others.

Each collection is defined by a <link> tag with an href attribute which includes the fully-qualified URL to the collection (which may exist on different servers) and a rel attribute to denote which collection is being specified.

<api driver='ec2' version='1.0'>
  <link href='http://fancycloudprovider.com/api/flavors' rel='flavors' />
  <link href='http://fancycloudprovider.com/api/instance-states' rel='instance_states' />
  <link href='http://fancycloudprovider.com/api/realms' rel='realms' />
  <link href='http://fancycloudprovider.com/api/images' rel='images' />
  <link href='http://fancycloudprovider.com/api/instances' rel='instances' />
</api>

Resources

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.

Basic relationships

Flavors

Within a cloud provider a flavor represents a configuration of resources upon which a machine may be deployed. A flavor 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) flavors as desired.

<flavors>
  <flavor href="http://fancycloudprovider.com/api/flavors/m1-small">
    <id>m1-small</id>
    <architecture>i386</architecture>
    <memory>1.7</memory>
    <storage>160</storage>
  </flavor>
  <flavor href="http://fancycloudprovider.com/api/flavors/m1-large">
    <id>m1-large</id>
    <architecture>x86_64</architecture>
    <memory>7.5</memory>
    <storage>850</storage>
  </flavor>
</flavors>

Each <flavor> block shall contain an href attribute providing a URL to manipulate a specific flavor, along with elements for each attribute of a flavor.

id A unique identifier for the flavor
architecture The architecture
- i386
- x86_64
memory The amount of RAM, in gigabytes.
storage The amount of local disk storage, in gigabytes.

At this time, flavor resources are immutable and read-only. In a future revision they may be mutable.

Realms

Within a cloud provider a realm 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.

<realms>
  <realm href="http://fancycloudprovider.com/api/realms/us">
    <id>us</id>
    <name>United States</name>
    <state>AVAILABLE</state>
    <limit/>
  </realm>
  <realm href="http://fancycloudprovider.com/api/realms/eu">
    <id>eu</id>
    <name>Europe</name>
    <state>AVAILABLE</state>
    <limit/>
  </realm>
</realms>

Each <realm> block shall contain an href attribute providing a URL to manipulate a specific realm, along with elements for each attribute of a realm.

id A unique identifier for the realm
name A short label
state Indicator of the current state of a realm
- AVAILABLE
- UNAVAILABLE
limit Limits applicable for the current requester

Images

An image is a platonic form of a machine. Images are not directly executable, but are a template for creating actual instances of machines.

The instances collection will return a set of all images available to the current user.

<images>
  <image href="http://fancycloudprovider.com/api/images/img1">
    <id>img1</id>
    <owner_id>fedoraproject</owner_id>
    <name></name>
    <description>Fedora 10</description>
    <architecture>x86_64</architecture>
  </image>
  <image href="http://fancycloudprovider.com/api/images/img2">
    <id>img2</id>
    <owner_id>fedoraproject</owner_id>
    <name></name>
    <description>Fedora 10</description>
    <architecture>i386</architecture>
  </image>
  <image href="http://fancycloudprovider.com/api/images/img3">
    <id>img3</id>
    <owner_id>ted</owner_id>
    <name></name>
    <description>JBoss</description>
    <architecture>i386</architecture>
  </image>
</images>

Each <image> block shall contain an href 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.

These attributes include

id A unique identifier for the image
owner_id An opaque identifier which indicates the owner of an image
name An optional short label describing the image
description An optional description describing the image more fully
architecture A description of the machine architecture of the image which may contain values such as:
- i386
- x86_64

At this time, image resources are immutable and read-only. In a future revision they will be mutable.

Instances

An instance is a concrete machine realized from an image. The images collection may be obtained by following the link from the primary entry-point.

<instances>
  <instance href="http://fancycloudprovider.com/api/instances/inst1">
    <id>inst1</id>
    <owner_id>larry</owner_id>
    <name>Production JBoss Instance</name>
    <image href="http://fancycloudprovider.com/api/images/img3"/>
    <flavor href="http://fancycloudprovider.com/api/flavors/m1-small"/>
    <realm href="http://fancycloudprovider.com/api/realms/us"/>

    <state>RUNNING</state>
    <actions>
      <link rel="reboot" href="http://fancycloudprovider.com/api/instances/inst1/reboot"/>
      <link rel="stop" href="http://fancycloudprovider.com/api/instances/inst1/stop"/>
    </actions>
    <public-addresses>
      <address>inst1.larry.fancycloudprovider.com</address>
    </public-addresses>

    <private-addresses>
      <address>inst1.larry.internal</address>
    </private-addresses>
  </instance>
</instances>

Each <instance> 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.

Simple attributes include

id A unique identifier for the instance
owner_id An opaque identifier which indicates the owner of an instance
name An optional short label describing the instance
image Provides a link to the platonic image from which the instance is based
flavor Provides a link to flavor of virtual hardware in use by the instance
realm Provides a link to the realm where the instance is deployed
state Indicator of the instance's current state
- PENDING
- STOPPED
- RUNNING

Multiple-valued attributes include

public-addresses Publicly routable IP addresses or names for the instance
private-addresses Private network IP addresses or names for the instance

In addition to the abovementioned attributes, each <instance> may contain an <actions> 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 <link> with an href attribute providing the URL, and a rel attribute providing a key to determine what the action will do.

Representative actions include

reboot
start
stop

Not all actions may be valid at all times for all instances. To invoke an action, a client must perform an HTTP POST to the URL indicated.

Creating a new Instance

Per usual REST architectural style, new instances are created by issuing an HTTP POST to the instances collection as defined through the primary entry-point URL. Data should be sent in application/x-www-form-urlencoded format.

To create a new instance, only one parameter is required

image_id The identifier (not URL) of the image from which to base the instance

Optional parameters may also be provided

realm_id The realm in which to launch the instance
flavor_id The machine flavor upon which to launch the instance
name A short label to identify the instance

If realm_id or flavor_id are not specified, the provider must select reasonable defaults. The architecture of the selected flavor must match the architecture of the specified image.

After POSTing the data, the server shall return a representation of the newly-created instance's XML, including a URL to retrieve the instance in the future.

Deltacloud - Many clouds. One API. No problem.

Deltacloud API

Creating a new Instance