The Deltacloud REST API

Apache Deltacloud is a REST-based (HATEOAS) cloud abstraction API. It enables management of resources in different IaaS clouds using a single API. There are back-end drivers communicating with each cloud provider's native API and the Deltacloud Core Framework provides the basis for implementing drivers to new IaaS clouds. Apache Deltacloud currently supports many back-end cloud providers.

With Deltacloud project, you don't have to limit yourself to a single cloud provider. Instead of taking care of a number of clouds, you are dealing with just one API abstraction.

Collections

The following terms describe abstractions used in the Apache Deltacloud API. Each collection represents an entity in the back-end provider cloud, such as a running virtual server or a server image. Please note that the list of supported collections may differ from cloud to cloud. Only the appropriate collections are exposed for a given back-end driver (e.g. the Microsoft Azure driver currently exposes only the Buckets collection).

Realms

A distinct organizational unit within the back-end cloud, for exapmle a datacenter. A realm may but does not necessarily represent the geographical location of the compute resources which you access.

Instances

A realized virtual server, running in a given back-end cloud. Instances are instantiated from server images.

Images

Templates (virtual machine images) from which instances are created. Each image defines the root partition and initial storage for the instance operating system.

Instance states

Instance states represent the instance lifecycle. at any time an instance is in one of states: start, pending, running, stopped, shutting_down, finished.

Keys

Keys represent credentials used to access a running instance. Keys can take the form of key (for example an RSA key) or of password (with username and password attributes).

Storage volume

A virtual storage device that can be attached to an instance and mounted by the OS.

Storage snapshot

Storage snapshots are copies, snapshots of a storage volume at a specified time.

Bucket

A container for data blobs. The organizational unit of a generic key ==> value based on data store (such as Rackspace CloudFiles or Amazon S3). Individual data items, blobs, are exposed as a subcollection under a bucket.

Blob

A generic binary data item that exists within a specified bucket (an object in Amazon S3 and Rackspace CloudFiles).

Address

Address represents an IP address. Depending on the back-end cloud provider, address can be public or private. Public address represents a unique, globally routable IP address, private address represents an address routable only within a private network.

Load Balancer

A load balancer allows a distribution of ingress network traffic received by a specified IP address to a number of instances.

Firewalls

Sets of rules that govern the accessibility of a running instance over the public Internet.

Metrics

Metrics collection provides useful information about your cloud resources, e.g. CPU utilization or network throughput. It may be helpful for developers for better scaling and monitoring. The collection is currently supported for Amazon EC2 cloud, collecting information from Amazon CloudWatch service, and Fujitsu GCP.

Client Requests

In accordance with REST principles, clients make requests through HTTP with the usual meanings assigned to the standard HTTP verbs GET, POST, PUT, and DELETE.

Besides the generally accepted REST design principles, Apache Deltacloud follows the guidelines discussed in the Fedora Project Cloud APIs Rest Style Guide.

The URL space of the API is structured into collections of resources. The top level entities used in the Deltacloud API are: realms, images, instance states, instances, keys, storage volumes, storage snapshots, blob storage, hardware profiles and drivers.

Authentication

The Deltacloud API server is stateless and does not keep any information about the current client. The Deltalcloud server does not store the credentials for the back-end cloud which the server is talking to. Instead, the server uses HTTP basic authentication and clients have to send the username/password for the back-end cloud on every request.

The specifics of what needs to be sent varies from cloud to cloud; some cloud providers request a username and password for API access, the others use special-purpose API keys. Check the list of the credentials to find out what kind of information a specific cloud provider expects.

Server responses

The server can respond to client requests in various formats. The appropriate response format is determined by HTTP content negotiation. The primary format is XML. The output is also available as JSON and as HTML (mostly for testing). Clients can also explicitly request a specific response format by including the format= request parameter (http://deltacloudserver.foo/api?format=xml or http://deltacloudserver.foo/api?format=json).

In general (especially for the HTML interface), list operations such as GET /api/realms will provide a list of objects of this resource type with only brief details. Full details can be retrieved by making a request GET /api/realms/:id to the URL of the individual realm.

API conventions

Any XML element which represents an object (such as an instance) has a href and an id attribute. The href attribute provides the URL at which object-specific actions can be performed (for example a GET action applied to the URL will return details of the object). The id provides an identifier of the object, which is unique within its collection (there is a unique id for each Instance, Image, Realm etc).

Objects also have a human-readable name. The name is provided in a <name/> child element of the object’s container tag.

API stability and evolution

Every change to the API is made in a way that allows old clients to work against newer versions of the API server.

You may come across the following changes in newer versions of the API:

On the other hand, these changes would violate API stability and therefore they are not made:

Online documentation

You can access an automatically generated documentation on every server running the Deltacloud Core API service through the URL http://localhost:3001/api/docs/. The documentation is both available in HTML and XML, though the XML format is not part of this specification and may change in an incompatible way.

API entry point