Skip to content
Pure Clojure language bindings for the Rackspace Cloud
Pull request Compare This branch is 110 commits ahead of shughes:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



Pure Clojure Bindings for the Rackspace Cloud



This project doesn't really aim to be anything special. As we need some functionality, we'll add it. Initial focus will be on supporting only a subset of Rackspace Cloud Services (version 2 Cloud Servers).


clj-rackspace is up on Clojars. You can add it to your project.clj for automatic download with the following:

(defproject your-project "1.2.3"
  :dependencies [[org.clojure/clojure "1.5.1"]
                  [clj-rackspace "0.1.1"]]

You can then use it in your project like so:

(ns your-project.client
  (:require [rackspace.api :as rax-api]))

Or from the REPL:

(require '[rackspace.api :as rax-api])

Running Example Code

The easiest way to get started with clj-rackspace is to play with it in the REPL. You'll need to download the code for this:

$ git clone
$ cd clj-rackspace

Now just do this at the command line prompt:

$ make shell

Which will dump you in the rackspace.api namespace:

nREPL server started on port 62531 on host
REPL-y 0.2.1
Clojure 1.5.1
    Docs: (doc function-name-here)
          (find-doc "part-of-name-here")
  Source: (source function-name-here)
 Javadoc: (javadoc java-object-or-class-here)
    Exit: Control+D or (exit) or (quit)
 Results: Stored in vars *1, *2, *3, an exception in *e


For the examples below, you will need to provide your own username, password, and any data returned from Rackspace Cloud services.

To make things easier to read in the examples below, let's set up pretty-printing:

rackspace.api=> (require '[clojure.pprint :refer [pprint]])

CloudServers Usage

Logging In

Via password:

rackspace.api=> (def response (login "alice" :password "z0mg11!!secret1!1"))

Via API key:

rackspace.api=> (login "alice" :apikey "0a12b33c444d5555ee0123456789ffff")
{:orig-content-encoding "gzip" ... }

You will need to pass one of the two, however:

rackspace.api=> (login "alice")

ExceptionInfo AuthError: Missing named parameter  ...

Working with Login Data

With our response data saved, we can now perform several operations with auth utility functions.

Getting the token:

rackspace.api=> (pprint (get-token response))
{:id "482664e7cf97408e82f512fad93abc98",
 :expires "2013-10-17T20:11:40.557-05:00",
 :tenant {:id "007007", :name "007007"},
 :RAX-AUTH:authenticatedBy ["PASSWORD"]}

Listing the regions:

rackspace.api=> (list-cloud-servers-regions response)
(:syd :dfw :ord :iad)

Getting all the endpoints:

rackspace.api=> (pprint (get-cloud-servers-endpoints response))
[{:region "SYD",
  :tenantId "007007",
  :publicURL "",
  :versionInfo "",
  :versionList "",
  :versionId "2"}
 {:region "DFW",
  :tenantId "007007",
  :publicURL "",
  :versionInfo "",
  :versionList "",
  :versionId "2"}
 {:region "ORD",
  :tenantId "007007",
  :publicURL "",
  :versionInfo "",
  :versionList "",
  :versionId "2"}
 {:region "IAD",
  :tenantId "007007",
  :publicURL "",
  :versionInfo "",
  :versionList "",
  :versionId "2"}]

Optionally, you may provide a version number (version 2 is assumed by default):

rackspace.api=> (pprint (get-cloud-servers-endpoints response :version 1))
[{:tenantId "007007",
  :publicURL "",
  :versionInfo "",
  :versionList "",
  :versionId "1.0"}]

If you know the region you want, you can get the URL for it simply with this:

rackspace.api=> (get-cloud-servers-region-url response :dfw)


This project was started in 2009 by Samuel Hughes. After a first implementation against the v1 API of Rackspace Cloud Servers, the project went into hibernation.

Clojure is a delight to code in, and although it supports fabulous Java interop, using jclouds from Clojure is a bit tedious. One alternative would be to take the Clojure-idiomatic example and grow that as a wrapper around jclouds. That was seriously considered. Another alterative was to take Samuel Hughes' work based on technomancy's clojure-http-client and develop a pure Clojure implementation.

That just sounded like more fun :-) So here we are.


There are two efforts driving this work:

  1. Rackspace Cloud Servers users who write in Clojure want to have a library that can use quickly, easily, and in a Clojure-idiomatic way.
  2. storm-deploy users would like to be able to deploy to Rackspace Cloud Servers.

A note about that last point: pallet (used by storm-deploy) currently uses jclouds, so it might simply be easier to use jclouds. Only time will tell. In the meantime, we'll have fun playing with a pure-Clojure implementation.


In the four years since this project was started, HTTP clients in Clojure have come a long way. We will be migrating away from the original implementation's choice of clojure-http-client.

The two commonly recommended clients are:

  • clj-http for synchronous/blocking client calls; this library is a Clojure wrapper for the Apache HTTP client library.
  • http.async.client for asynchronous usage; it's based on the Asynchronous Http Client for Java.

We have started with the synchronous client. Hopefully, we'll add async support at some point in the future. No promises. We'll defer that for later.


To use or develop against Rackspace Cloud APIs, we've provided the following (hopefully) useful links:

Something went wrong with that request. Please try again.