Using API

Clients

Instead of dealing with HTTP interface you can use various clients to communicate with Deltacloud server.

The Deltacloud Ruby Client

You need to install Ruby client seperately to the Deltacloud API server. Assuming you already have Ruby and RubyGems setup, you can install the Deltacloud client by simply typing:

$ sudo gem install deltacloud-client

The Deltacloud client consists of a Ruby library (packaged as a Ruby gem) which you can use to interact with the Deltacloud server and control your cloud infrastructure across cloud providers.

To use the client, you must require deltacloud:

require 'deltacloud'

Connect to a Deltacloud provider:

require 'deltacloud'

api_url      = 'http://localhost:3001/api'
api_name     = 'mockuser'
api_password = 'mockpassword'

client = DeltaCloud.new( api_name, api_password, api_url )

# work with client here

In addition to creating a client, you can specify operations within a block included on the initialization.

DeltaCloud.new( api_name, api_password, api_url ) do |client|
  # work with client here
end

In case of a failure, any underlying HTTP transport exceptions will be thrown away and returned back to the caller.

To work with another driver, just switch the client:

client = DeltaCloud.new( api_name, api_password, api_url )

# switch the client to use EC2 driver
ec2 = client.with_config(:driver => :ec2)

# switch the client to use OpenStack driver
openstack = client.with_config(:driver => :openstack)

Work with the Ruby client

HTTP clients - cURL

Basically, you interact with the Deltacloud server via HTTP calls, so you can use any HTTP client to talk to Deltacloud using the REST API.

cURL is a popular command line tool available on most modern linux distributions. See the following examples to learn how to use cURL to interact with Deltacloud. There is an assumption that the Deltacloud server is running on locahost:3001 and was started with the 'ec2' driver (i.e., deltacloudd -i ec2 ).

Get a list of all images available in the back-end cloud:

curl  --user "pGbAJ1TsVg5PKs3BK27O:dPs47ralgBlldqYNbLg3scthsg4g8v0L9d6Mb5DK"
"http://localhost:3001/api/images?format=xml"

The cURL --user option is used to specify the username:password credentials for access to the back-end cloud provider (Amazon EC2 in this case).

Create a new instance from the image with id 'ami-f51aff9c', in realm 'us-east-1c', with the hardware profile 'c1.medium', in firewall 'default':

curl -X POST -F "keyname=eftah" -F "image_id=ami-f51aff9c"
-F "realm_id=us-east-1c" -F "hwp_id=c1.medium" -F "firewalls1=default"
--user "pGbAJ1TsVg5PKs3BK27O:dPs47ralgBlldqYNbLg3scthsg4g8v0L9d6Mb5DK"
"http://localhost:3001/api/instances?format=xml"

Delete a firewall called 'develgroup':

curl -X DELETE
--user "pGbAJ1TsVg5PKs3BK27O:dPs47ralgBlldqYNbLg3scthsg4g8v0L9d6Mb5DK"
http://localhost:3001/api/firewalls/develgroup?format=xml

Create a blob called 'my_new_blob' within the bucket 'mybucket' from a local file with HTTP PUT specifying its content type and setting some metadata key:value pairs:

curl -H 'content-type: text/html' -H 'X-Deltacloud-Blobmeta-Name:mariosblob'
-H 'X-Deltacloud-Blobmeta-Version:2.1' --upload-file
"/home/marios/Desktop/somefile.html"
--user "pGbAJ1TsVg5PKs3BK27O:dPs47ralgBlldqYNbLg3scthsg4g8v0L9d6Mb5DK"
http://localhost:3001/api/buckets/mybucket/my_new_blob?format=xml

Retrieve blob metadata for the blob called 'my_new_blob':

curl -iv -X HEAD
--user "pGbAJ1TsVg5PKs3BK27O:dPs47ralgBlldqYNbLg3scthsg4g8v0L9d6Mb5DK"
http://localhost:3001/api/buckets/mybucket/my_new_blob?format=xml

The '-iv' flags will ensure that cURL displays the request and response headers (blob metadata are reported in the response headers with an empty response body).

Working with cURL

Libdeltacloud Client (C library)

Libdeltacloud is a C/C++ library for accessing the Deltacloud API. It exports convenient structures and functions for manipulating cloud objects through the Deltacloud API.

Get the source code:

$ git clone git://git.fedorahosted.org/deltacloud/libdeltacloud.git

As of version 0.9, libdeltacloud is mostly API stable, but not ABI stable. The difference between the two is subtle but important. A library that is ABI (Application Binary Interface) stable means, that programs using the library don't need to be modified nor re-compiled when a new version of the library comes out. A library that is API (Application Programming Interface) stable means that programs using the library don't need to be modified, but may need to be re-compiled when a new version of the library comes out. The reason is that the sizes of structures in the library might change, which can lead to a misunderstanding between what the library and the program thinks the size of a structure is.

Due to the magic of libtool versioning, programs built against an older version of libdeltacloud will refuse to run against a newer version of libdeltacloud if the size of the structures has changed. If this happens, then the program must be recompiled against the newer libdeltacloud.

Libdeltacloud documentation