How to use the first generation of Rackspace Cloud Server API

Problem description

Using the Rackspace Cloud API [1] for the Cloud Servers how to authenticate yourself.
Being authenticated how to execute and test the various API calls that are listed in the API specification [2]

Solution

• Authentication

To authenticate you need the user name and the API key. You can find these on your cloud control (CC) portal [3] under the "Your Accout" -> "API Access" section.

If you use the new CC Panel you will find it under the user name on the top - right section of the screen. Once clicked you will see the "API Keys" menu that lists the key and the user name again.

Example output:

curl --verbose -H "X-Auth-User: user" -H "X-Auth-Key: key"  https://lon.auth.api.rackspacecloud.com/v1.0
* About to connect() to lon.auth.api.rackspacecloud.com port 443 (#0)
*   Trying 94.236.107.224... connected
* successfully set certificate verify locations:
*   CAfile: /usr/ssl/certs/ca-bundle.crt
  CApath: none
* SSLv3, TLS handshake, Client hello (1):
* SSLv3, TLS handshake, Server hello (2):
* SSLv3, TLS handshake, CERT (11):
* SSLv3, TLS handshake, Server finished (14):
* SSLv3, TLS handshake, Client key exchange (16):
* SSLv3, TLS change cipher, Client hello (1):
* SSLv3, TLS handshake, Finished (20):
* SSLv3, TLS change cipher, Client hello (1):
* SSLv3, TLS handshake, Finished (20):
* SSL connection using RC4-SHA
* Server certificate:
*        subject: C=US; ST=Texas; L=San Antonio; O=Rackspace Managed Hosting; OU=The Rackspace Cloud; OU=Terms of use at www.verisign.com/rpa (c)05; CN=lon.auth.api.rackspacecloud.com
*        start date: 2010-11-02 00:00:00 GMT
*        expire date: 2015-11-01 23:59:59 GMT
*        common name: lon.auth.api.rackspacecloud.com (matched)
*        issuer: C=US; O=VeriSign, Inc.; OU=VeriSign Trust Network; OU=Terms of use at https://www.verisign.com/rpa (c)10; CN=VeriSign Class 3 Secure Server CA - G3
*        SSL certificate verify ok.
> GET /v1.0 HTTP/1.1
> User-Agent: curl/7.22.0 (i686-pc-cygwin) libcurl/7.22.0 OpenSSL/0.9.8r zlib/1.2.5 libidn/1.22 libssh2/1.2.7
> Host: lon.auth.api.rackspacecloud.com
> Accept: */*
> X-Auth-User: user
> X-Auth-Key: key
>
< HTTP/1.1 204 No Content
< Server: Apache/2.2.3 (Red Hat)
< vary: X-Auth-Token,X-Auth-Key,X-Storage-User,X-Storage-Pass
< X-Storage-Url: https://storage101.lon3.clouddrive.com/v1/MossoCloudFS_c99f3ebf-f27d-4933-94b7-9e9ebf2bc7cd
< Cache-Control: s-maxage=79412
< Content-Type: text/xml
< Date: Sun, 22 Jul 2012 20:33:45 GMT
< X-Auth-Token: a27...e
< X-Server-Management-Url: https://lon.servers.api.rackspacecloud.com/v1.0/10001641
< X-Storage-Token: a27...9de
< Connection: Keep-Alive
< X-CDN-Management-Url: https://cdn3.clouddrive.com/v1/MossoCloudFS_c99f3ebf-f27d-4933-94b7-9e9ebf2bc7cd
< Content-Length: 0
<
* Connection #0 to host lon.auth.api.rackspacecloud.com left intact
* Closing connection #0
* SSLv3, TLS alert, Client hello (1):

The most important values we have to copy from the output for further work are:

X-Auth-Token: a27....b9de
X-Server-Management-Url: https://lon.servers.api.rackspacecloud.com/v1.0/10001641

• Issuing more requests, example of how to list available cloud flavors

curl --verbose -H "X-Auth-Token: a27....9de"  https://lon.servers.api.rackspacecloud.com/v1.0/10001641/flavors
* About to connect() to lon.servers.api.rackspacecloud.com port 443 (#0)
*   Trying 212.64.148.15... connected
* successfully set certificate verify locations:
*   CAfile: /usr/ssl/certs/ca-bundle.crt
  CApath: none
* SSLv3, TLS handshake, Client hello (1):
* SSLv3, TLS handshake, Server hello (2):
* SSLv3, TLS handshake, CERT (11):
* SSLv3, TLS handshake, Server finished (14):
* SSLv3, TLS handshake, Client key exchange (16):
* SSLv3, TLS change cipher, Client hello (1):
* SSLv3, TLS handshake, Finished (20):
* SSLv3, TLS change cipher, Client hello (1):
* SSLv3, TLS handshake, Finished (20):
* SSL connection using AES256-SHA
* Server certificate:
*        subject: C=US; ST=Texas; L=San Antonio; O=Rackspace Managed Hosting; OU=The Rackspace Cloud; OU=Terms of use at www.verisign.com/rpa (c)05; CN=lon.servers.api.rackspacecloud.com
*        start date: 2010-11-02 00:00:00 GMT
*        expire date: 2015-11-01 23:59:59 GMT
*        common name: lon.servers.api.rackspacecloud.com (matched)
*        issuer: C=US; O=VeriSign, Inc.; OU=VeriSign Trust Network; OU=Terms of use at https://www.verisign.com/rpa (c)10; CN=VeriSign Class 3 Secure Server CA - G3
*        SSL certificate verify ok.
> GET /v1.0/10001641/flavors HTTP/1.1
> User-Agent: curl/7.22.0 (i686-pc-cygwin) libcurl/7.22.0 OpenSSL/0.9.8r zlib/1.2.5 libidn/1.22 libssh2/1.2.7
> Host: lon.servers.api.rackspacecloud.com
> Accept: */*
> X-Auth-Token: a277...9de
>
< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< vary:  Accept, Accept-Encoding, X-Auth-Token
< Last-Modified: Tue, 21 Jun 2011 21:09:45 GMT
< X-PURGE-KEY: /flavors
< Cache-Control: s-maxage=1800
< Content-Type: application/json
< Content-Length: 249
< Date: Sun, 22 Jul 2012 20:34:35 GMT
< X-Varnish: 1603286324
< Age: 0
< Via: 1.1 varnish
< Connection: keep-alive
<
* Connection #0 to host lon.servers.api.rackspacecloud.com left intact
* Closing connection #0
* SSLv3, TLS alert, Client hello (1):
{
  flavors => [
    { id => 1, name => "256 server" },
    { id => 2, name => "512 server" },
    { id => 3, name => "1GB server" },
    { id => 4, name => "2GB server" },
    { id => 5, name => "4GB server" },
    { id => 6, name => "8GB server" },
    { id => 7, name => "15.5GB server" },
    { id => 8, name => "30GB server" },
  ],
}

• Example of how to list available image types (type of operating systems/Linux distributions)

curl -H "X-Auth-Token: a2772b...b9de" https://lon.servers.api.rackspacecloud.com/v1.0/10001641/images | json_xs -t dump 
{
  images => [
    { id => 24,  name => "Windows Server 2008 SP2 x64" },
    { id => 31,  name => "Windows Server 2008 SP2 x86" },
    { id => 56,  name => "Windows Server 2008 SP2 x86 + SQL Server 2008 R2 Standard" },
    { id => 57,  name => "Windows Server 2008 SP2 x64 + SQL Server 2008 R2 Standard"},
    { id => 85,  name => "Windows Server 2008 R2 x64" },
    { id => 86,  name => "Windows Server 2008 R2 x64 + SQL Server 2008 R2 Standard" },
    { id => 89,  name => "Windows Server 2008 R2 x64 + SQL Server 2008 R2 Web"},
    { id => 91,  name => "Windows Server 2008 R2 x64 + SQL Server 2012 Standard" },
    { id => 92,  name => "Windows Server 2008 R2 x64 + SQL Server 2012 Web" },
    { id => 100, name => "Arch 2011.10" },
    { id => 103, name => "Debian 5 (Lenny)" },
    { id => 104, name => "Debian 6 (Squeeze)" },
    { id => 108, name => "Gentoo 11.0" },
    { id => 109, name => "openSUSE 12" },
    { id => 110, name => "Red Hat Enterprise Linux 5.5" },
    { id => 111, name => "Red Hat Enterprise Linux 6" },
    { id => 112, name => "Ubuntu 10.04 LTS" },
    { id => 114, name => "CentOS 5.6" },
    { id => 115, name => "Ubuntu 11.04" },
    { id => 116, name => "Fedora 15" },
    { id => 118, name => "CentOS 6.0" },
    { id => 119, name => "Ubuntu 11.10" },
    { id => 120, name => "Fedora 16" },
    { id => 121, name => "CentOS 5.8" },
    { id => 122, name => "CentOS 6.2" },
    { id => 125, name => "Ubuntu 12.04 LTS" },
    { id => 126, name => "Fedora 17" },
    { id => 10776442, name => "test3" },
    { id => 10992583, name => "test2" },
    { id => 11019155, name => "Mytest1" },
    { id => 11208053, name => "windows2008R2x64Image" },
    { id => 11236707, name => "w2k8x86sp2-090712-IIS" },
  ],
}

The above outputs has been changed a little bit to include the HTTP headers as well as nice formatted server payload. The payload was generated using this command:

curl -H "X-Auth-Token: a27...de" https://lon.servers.api.rackspacecloud.com/v1.0/10001641/flavors | json_xs -t dump

• Issuing a request to create a cloud server

And our important request to create a cloud server with a help of the API request.

cat create-cloud.txt 
{
    "server" : {
        "name" : "rc-test1",
        "imageId" : 112,
        "flavorId" : 1,
        "metadata" : {
            "key1" : "value1"
        }
    }
}

curl --verbose -d @create-cloud.txt -H "Content-Type: application/json" -H "X-Auth-Token: a2772b...9de" https://lon.servers.api.rackspacecloud.com/v1.0/10001641/servers | json_xs -t dump 
* About to connect() to lon.servers.api.rackspacecloud.com port 443 (#0)
*   Trying 212.64.148.15...   % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0connected
* Connected to lon.servers.api.rackspacecloud.com (212.64.148.15) port 443 (#0)
* successfully set certificate verify locations:
*   CAfile: none
  CApath: /etc/ssl/certs
* SSLv3, TLS handshake, Client hello (1):
} [data not shown]
* SSLv3, TLS handshake, Server hello (2):
{ [data not shown]
* SSLv3, TLS handshake, CERT (11):
{ [data not shown]
* SSLv3, TLS handshake, Server finished (14):
{ [data not shown]
* SSLv3, TLS handshake, Client key exchange (16):
} [data not shown]
* SSLv3, TLS change cipher, Client hello (1):
} [data not shown]
* SSLv3, TLS handshake, Finished (20):
} [data not shown]
* SSLv3, TLS change cipher, Client hello (1):
{ [data not shown]
* SSLv3, TLS handshake, Finished (20):
{ [data not shown]
* SSL connection using AES256-SHA
* Server certificate:
*   subject: C=US; ST=Texas; L=San Antonio; O=Rackspace Managed Hosting; OU=The Rackspace Cloud; OU=Terms of use at www.verisign.com/rpa (c)05; CN=lon.servers.api.rackspacecloud.com
*   start date: 2010-11-02 00:00:00 GMT
*   expire date: 2015-11-01 23:59:59 GMT
*   common name: lon.servers.api.rackspacecloud.com (matched)
*   issuer: C=US; O=VeriSign, Inc.; OU=VeriSign Trust Network; OU=Terms of use at https://www.verisign.com/rpa (c)10; CN=VeriSign Class 3 Secure Server CA - G3
*   SSL certificate verify ok.
> POST /v1.0/10001641/servers HTTP/1.1
> User-Agent: curl/7.21.3 (i686-pc-linux-gnu) libcurl/7.21.3 OpenSSL/0.9.8o zlib/1.2.3.4 libidn/1.18
> Host: lon.servers.api.rackspacecloud.com
> Accept: */*
> Content-Type: application/json
> X-Auth-Token: a2772b...
> Content-Length: 158
> 
} [data not shown]
100   158    0     0  100   158      0     49  0:00:03  0:00:03 --:--:--    50< HTTP/1.1 202 Accepted
< Server: Apache-Coyote/1.1
< vary:  Accept, Accept-Encoding, X-Auth-Token
< Cache-Control: no-cache
< Content-Type: application/json
< Content-Length: 272
< Date: Sun, 22 Jul 2012 21:33:26 GMT
< X-Varnish: 1603293323
< Age: 0
< Via: 1.1 varnish
< Connection: keep-alive
< 
 36   430    0     0  100   158      0     43  0:00:03  0:00:03 --:--:--    44{ [data not shown]
100   430  100   272  100   158     74     42  0:00:03  0:00:03 --:--:--    75* Connection #0 to host lon.servers.api.rackspacecloud.com left intact

* Closing connection #0
* SSLv3, TLS alert, Client hello (1):
} [data not shown]
{
  server => {
    addresses => { private => ["10.178.14.178"], public => ["5.79.0.178"] },
    adminPass => "vS2Ec60xDrc-test1",
    flavorId => 1,
    hostId => "0fa7e40134ef21228895618b21e7090b",
    id => 10195258,
    imageId => 112,
    metadata => { key1 => "value1" },
    name => "rc-test1",
    progress => 0,
    status => "BUILD",
  },
}

References
http://docs.rackspace.com/api/
[2] http://docs.rackspace.com/servers/api/v1.0/cs-devguide/content/Overview-d1e70.html
[3] https://lon.manage.rackspacecloud.com
[4] http://docs.rackspace.com/servers/api/v1.0/cs-devguide/content/Auth-Request.html