The API entry point

Any part of the official API can be reached through the main entry point, by default http://localhost:3001/api. The entry point lists the resources for the current cloud provider, which the server knows about. For example, for the Amazon EC2 driver these are:

  • instances
  • instance states
  • images
  • realms

Example request:

GET /api?format=xml HTTP/1.1
Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
Host: localhost:3001
Accept: */*

Server response:

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 1439

<api driver='ec2' version='0.3.0'>
  <link href='http://localhost:3001/api/instance_states' rel='instance_states'>
  </link>
  <link href='http://localhost:3001/api/drivers' rel='drivers'>
  </link>
  <link href='http://localhost:3001/api/addresses' rel='addresses'>
  </link>
  <link href='http://localhost:3001/api/hardware_profiles' rel='hardware_profiles'>
  </link>
  <link href='http://localhost:3001/api/firewalls' rel='firewalls'>
  </link>
  <link href='http://localhost:3001/api/storage_volumes' rel='storage_volumes'>
  </link>
  <link href='http://localhost:3001/api/images' rel='images'>
    <feature name='owner_id'>
    </feature>
  </link>
  <link href='http://localhost:3001/api/realms' rel='realms'>
  </link>
  <link href='http://localhost:3001/api/buckets' rel='buckets'>
    <feature name='bucket_location'>
    </feature>
  </link>
  <link href='http://localhost:3001/api/instances' rel='instances'>
    <feature name='user_data'>
    </feature>
    <feature name='authentication_key'>
    </feature>
    <feature name='firewalls'>
    </feature>
    <feature name='instance_count'>
    </feature>
    <feature name='attach_snapshot'>
    </feature>
  </link>
  <link href='http://localhost:3001/api/storage_snapshots' rel='storage_snapshots'>
  </link>
  <link href='http://localhost:3001/api/keys' rel='keys'>
  </link>
  <link href='http://localhost:3001/api/load_balancers' rel='load_balancers'>
  </link>
</api>

Some implementations for the Apache Deltacloud API may not support all resource types defined by API. For example, a Deltacloud instance pointing at a storage-only service will not expose compute resources like instances and hardware profiles.

Features

The Apache Deltacloud API defines the standard behavior and semantics for each of the resource types as a baseline for any API implementation. It is often desirable to enhance standard API behavior with specific features. The API also defines all features that can be supported by the API implementation - each of them has a fixed predefined meaning. For example, the feature user_name indicates that a user-specified name can be assigned to an instance when it is created. Features are advertised in the top-level entry point as illustrated below:

<api driver='mock' version='0.3.0'>
  ...
  <link href='http://localhost:3001/api/instances' rel='instances'>
    <feature name='hardware_profiles'></feature>
    <feature name='user_name'></feature>
    <feature name='authentication_key'></feature>
  </link>
  ...
</api>

These features are available to each collection in the Deltacloud API:

Feature Collection Operation Description
owner_id Images GET /api/images allows filtering of the image list by owner_id
user_name Instances POST /api/instances accepts a user-defined name on instance creation
user_data Instances POST /api/instances provide user-defined data that is accessible by the running instance
user_iso Instances POST /api/instances provides a base64 encoded gzipped ISO file accessible as CD-ROM drive by the running instnace
user_files Instances POST /api/instances accept files that will be placed into the launched instance
firewalls Instances POST /api/instances put the instance into one or more firewalls on launch
authentication_key Instances POST /api/instances provides the authentication key to access the instance
authentication_password Instances POST /api/instances provides the password to access the running instance
instance_count Instances POST /api/instances specifies the number of instances to launch in one operation
attach_snapshot Instances POST /api/instances attaches a storage snapshot to an instance as a storage volume
sandboxing Instances POST /api/instances launches an instance from a sandbox image (Gogrid specific)
bucket_location Buckets POST /api/buckets specifies a location that the bucket should be created in (e.g. specific cloud-provider datacenter)

Compute resources