Using the API in Code

Deltacloud also provides a variety of clients. They all encapsulate the HTTP conversation with a Deltacloud server and make it easier to consume the REST-based API in your programs. As an example, I will show a small script that gets the list of all instances from a Deltacloud server and then polls the server for changes in the instance’s state.

Before I can do that, I need to install the Ruby Deltacloud client; with yum, run:

yum install rubygem-deltacloud-client

With gem, use

gem install deltacloud-client

The example script can be seen in Listing 1. After saving the script in example.rb , you can run it with

ruby example.rb URL USER PASSWORD

against your Deltacloud server. The output it produces will be something like this:

Found 4 instances in the following states:
        RUNNING 4
Polling for changes (Ctrl-C to end)
inst1 changed from RUNNING to STOPPED
inst1 changed from STOPPED to RUNNING
^C

The important parts are in line 4 of the listing, which initializes the Deltacloud client with the URL and credentials provided on the command line, and lines 6 and 19, which retrieve a list of all instances and then check each instance for changes. All the minutiae of making HTTP requests and deserializing the responses into objects is handled by the Deltacloud client library.

You can run this script against any server the Deltacloud supports simply by changing the URL you pass in (and the corresponding username and password) as described in the previous section. Running it against the URL http://HOSTNAME:PORT/api;driver=ec2;provider=us-west-1 will watch for state changes in EC2’s us-west-1 region, and running it against http://HOSTNAME:PORT/api;driver=gogrid will do the same for GoGrid. The script could be enhanced easily to watch state changes in all the clouds one has access to.

Listing 1. Get a List of All Instances from a Deltacloud Server and Poll the Server for Changes in State

01 require 'rubygems'
02 require 'deltacloud'

03 URL, USER, PASSWORD = ARGV

04 client = DeltaCloud.new(USER, PASSWORD, URL)

05 summary = Hash.new(0)
06 state = client.instances.inject({}) do |state, inst|
07   state[inst.id] = inst.state
08   summary[inst.state] += 1
09   state
10 end

11 total = summary.values.inject(0) { |sum, i| sum += i }
12 puts "Found #{total} instances in the following states:"
13 summary.keys.sort.each do |s|
14   printf "%20s %d\n", s, summary[s]
15 end

16 puts "Polling for changes (Ctrl-C to end)"
17 loop do
18   sleep 2
19   client.instances.each do |inst|
20    if state[inst.id] != inst.state
21     if state[inst.id]
22      puts "#{inst.id} changed from #{state[inst.id]} to #{inst.state}"
23     else
24      puts "#{inst.id} was created and is now #{inst.state}"
25     end
26     state[inst.id] = inst.state
27    end
28   end
29 end