• Home
• Download
• Contribute
• Documentation

• Overview
• REST API
• Drivers
• Framework
• Ruby Client

Deltacloud API

• REST
• Authentication
• Primary Entry Point
• Resources
  • Hardware Profiles
  • Realms
  • Images
  • Instances

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.

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.

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 application/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, hardware profiles 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/hardware_profiles' rel='hardware_profiles' />
  <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.

Hardware Profiles

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

<hardware_profiles>
  <hardware_profile href='http://fancycloudprovider.com/api/hardware_profiles/m1-small' id='m1-small'>
    <property kind='fixed' name='storage' unit='GB' value='160' />
    <property kind='fixed' name='architecture' unit='label' value='i386' />
    <property kind='fixed' name='cpu' unit='count' value='1' />
    <property kind='fixed' name='memory' unit='MB' value='1740.8' />
  </hardware_profile>

Each <hardware_profile> block shall contain an href attribute providing a URL to manipulate a specific profile, along with property elements for each attribute of the hardware.

• id is a unique identifier for the profile
• property describes each of the hardware aspects

Properties have the following attributes:

• name the type of the property: e.g. memory or storage
• unit the units in which the value is specified: MB, GB, count or label
• value the actual value of the property. It depends on the specified unit: 1024, 2 on x86_64
• kind describes the values to chose from.
  • fixed only the value specified in the property is available
  • enum a list of available values is provided
  • range available values are described by a numeric range

When the kind is either an enum or a range, there must be two additional elements specified. One that specifies the allowed values and the second with a way of picking a value.

In the non-fixed case, the value property attribute specifies the default value.

  <hardware_profile href='http://fancycloudprovider.com/api/hardware_profiles/m1-xlarge' id='m1-xlarge'>
    <property kind='enum' name='storage' unit='GB' value='1024'>
      <param href='http://fancycloudprovider.com/api/instances' method='post' name='hwp_storage' operation='create' />
      <enum>
        <entry value='1024' />
        <entry value='2048' />
        <entry value='4096' />
      </enum>
    </property>
    <property kind='fixed' name='architecture' unit='label' value='x86_64' />
    <property kind='fixed' name='cpu' unit='count' value='4' />
    <property kind='range' name='memory' unit='MB' value='12288'>
      <param href='http://fancycloudprovider.com/api/instances' method='post' name='hwp_memory' operation='create' />
      <range first='12288' last='32768' />
    </property>
  </hardware_profile>
</hardware_profiles>

At this time, hardware profile 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'>
    <name>United States</name>
    <state>AVAILABLE</state>
    <limit/>
  </realm>
  <realm href="http://fancycloudprovider.com/api/realms/eu" id='eu'>
    <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'>
    <owner_id>fedoraproject</owner_id>
    <name>Fedora 10</name>
    <description>Fedora 10</description>
    <architecture>x86_64</architecture>
  </image>
  <image href="http://fancycloudprovider.com/api/images/img2" id='img2'>
    <owner_id>fedoraproject</owner_id>
    <name>Fedora 10</name>
    <description>Fedora 10</description>
    <architecture>i386</architecture>
  </image>
  <image href="http://fancycloudprovider.com/api/images/img3" id='img3'>
    <owner_id>ted</owner_id>
    <name>JBoss</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'>
    <owner_id>larry</owner_id>
    <name>Production JBoss Instance</name>
    <image href="http://fancycloudprovider.com/api/images/img3"/>
    <hardware_profile href="http://fancycloudprovider.com/api/hardware_profiles/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
• hardware_profile Provides a link to the hardware profile 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
• hwp_name The hardware profile upon which to launch the instance
• name A short label to identify the instance

If realm_id or hwp_name are not specified, the provider must select reasonable defaults. The architecture of the selected harware profile 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.