Using the Rackspace API is not that difficult. The Rackspace API is basically just a method of working. Basically, you send all of your calls to a central location, known as the API endpoint.

At the API endpoint your HTTP request is processed, and an output returned. It really is just as simple as that. Rackspace provide an identity service, that allows you to make these requests securely via SSL certificate, meaning that the exchange is secured via strong encryption. In order to start interacting with the API we need to know three things.

1. The Cloud Primary Username, the Account Number being used on the account, and the API Key.

This can be found via the mycloud.rackspace.com control panel

Top Right button 'username' - > Account Settings

You now have the Primary user's USERNAME, API_KEY and the ACCOUNT_NUMBER and are ready to start making API calls.

2. Making your first request - authorising with identity endpoint

In order to proceed with your login credentials and make your first API call, you'll need to know the address of the identity server. I'll provide it, this is all you need to get started with API.

USERNAME='yourmycloudusernamegoeshere'
APIKEY='yourapikeygoeshere'

ACCOUNT_NUMBER=100

curl https://identity.api.rackspacecloud.com/v2.0/tokens -X POST -d '{ "auth":{"RAX-KSKEY:apiKeyCredentials": { "username":"'$USERNAME'", "apiKey": "'$APIKEY'" }} }' -H "Content-type: application/json" |  python -mjson.tool | grep -A5 endpoint

TOKEN=`curl https://identity.api.rackspacecloud.com/v2.0/tokens -X POST -d '{ "auth":{"RAX-KSKEY:apiKeyCredentials": { "username":"'$USERNAME'", "apiKey": "'$APIKEY'" }} }' -H "Content-type: application/json" |  python -mjson.tool | grep -A5 token | grep id | cut -d '"' -f4`

echo $TOKEN

The above script allows you to set USERNAME, APIKEY and ACCOUNT_NUMBER as a variable, that can be used by our curl request. The curl request is simply an HTTP request, like you would make in a normal web browser. The only difference is, there is an API application listening for our input on the website, at what is called the identity endpoint, and when it receives the Cloud Username and API key, and account number from us, it goes to look, and checks that the credentials you provided for the account are valid. And if they are, it will return to you a TOKEN. All requests, after a successful authentication to the identity endpoint are made referring to this TOKEN, from that point it is the only 'password' you need.

This token is like a temporary key, that will last for 24 hours.

As long as the TOKEN is valid, you can now use this to make additional API calls, to different endpoints (other than identity), to carry out a whole host of different tasks, such as imaging and rebuilding cloud-servers, listing all DNS records or CDN's on a Cloud Account, Creating Dbaas backup schedules, and much much more!

Now we're finally authorised and we've got a token to interact with the API, let's check what we can do.

3. Making your Second Request - obtaining the API endpoints for each product

Each product has a separate API Endpoint, for instance the API Endpoint for NOVA (Cloud-Servers) is different to the API Endpoint for CINDER (Cloud Block Storage) and also different from TROVE (Cloud Databases as a service or dbaas). In order to create scripts for each endpoint, we need to know what they are. So lets create a script that gets all the API endpoints.

The good news is part 2 already output all the endpoints, if your wondering, this line does it:

curl https://identity.api.rackspacecloud.com/v2.0/tokens -X POST -d '{ "auth":{"RAX-KSKEY:apiKeyCredentials": { "username":"'$USERNAME'", "apiKey": "'$APIKEY'" }} }' -H "Content-type: application/json" |  python -mjson.tool | grep -A5 endpoint

Example Output:

     ... (reduced for simplicity)

           "endpoints": [
                    {
                        "publicURL": "https://cdn3.clouddrive.com/v1/MossoCloudFS_100",
                        "region": "LON",
                        "tenantId": "MossoCloudFS_100"
                    }

Each endpoint defined looks like above and should indicate which product is for just by the convention of the naming.

However, not only are the different product API endpoints output by this command, but also the TOKEN, and in fact, pretty much all of the information is output. That is why we use this next line, to create a variable that we'll call TOKEN, that variable will hold the KEY we use to interact with the API from that point. However, in order for the TOKEN variable to be 'passed' to other scripts, we need to make sure that we get rid of all the extra data surrounding the TOKEN.

TOKEN=`curl https://identity.api.rackspacecloud.com/v2.0/tokens -X POST -d '{ "auth":{"RAX-KSKEY:apiKeyCredentials": { "username":"'$USERNAME'", "apiKey": "'$APIKEY'" }} }' -H "Content-type: application/json" |  python -mjson.tool | grep -A5 token | grep id | cut -d '"' -f4`

As you can see we needed to use GREP to remove the lines which are after token, and we needed to use grep to remove the line which contains the id and cut to remove the specific part of that line which has the password.

Everything needs to be exact. When learning the API, this can be really off-putting.


4. Making your Next Requests - the world awaits!

So far you've successfully been able to authorise yourself with the API identity endpoint, and, you've successfully retrieved a list of all the endpoints on this account. Now you need to use one of the endpoints. Let's use the example endpoint from section 3 and list all the CDN's on this account ID 100.

The API reports that the CDN endpoint is as follows, so this is what we use for the API_ENDPOINT variable

https://cdn3.clouddrive.com/v1/MossoCloudFS_100

Finished Script

#!/bin/bash

# Author: Adam Bull, Rackspace LTD
# Date: January 2017
# Email: adam.bull@rackspace.co.uk
# Use: This script is used for listing CDN

USERNAME='mycloudusername'
APIKEY='mycloudapikey'

TOKEN=`curl https://identity.api.rackspacecloud.com/v2.0/tokens -X POST -d '{ "auth":{"RAX-KSKEY:apiKeyCredentials": { "username":"'$USERNAME'", "apiKey": "'$APIKEY'" }} }' -H "Content-type: application/json" |  python -mjson.tool | grep -A5 token | grep id | cut -d '"' -f4`

# Your CDN Endpoint will look longer than _100
# I removed the full customer ID for security of my own
# account, use whatever the output endpoints were for you in section 2 or 3. Ask in this thread if your still having issues and we'll help you get it right!

API_ENDPOINT="https://cdn3.clouddrive.com/v1/MossoCloudFS_100"


curl -v -X GET $API_ENDPOINT/?format=json \
-H "X-Auth-Token: $TOKEN" | python -mjson.tool

Executing the Script

chmod +x get-cdn-list.sh
./get-cdn-list.sh

What the output looks like

# ./list-cdn.sh
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  5310  100  5195  100   115   8071    178 --:--:-- --:--:-- --:--:--  8079
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0* About to connect() to cdn3.clouddrive.com port 443 (#0)
*   Trying 2a00:1a48:7900::200...
* Connected to cdn3.clouddrive.com (2a00:1a48:7900::200) port 443 (#0)
* Initializing NSS with certpath: sql:/etc/pki/nssdb
*   CAfile: /etc/pki/tls/certs/ca-bundle.crt
  CApath: none
* SSL connection using TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
* Server certificate:
* 	subject: CN=cdn3.clouddrive.com
* 	start date: Oct 20 00:00:00 2016 GMT
* 	expire date: Jan 19 23:59:59 2019 GMT
* 	common name: cdn3.clouddrive.com
* 	issuer: CN=thawte DV SSL SHA256 CA,OU=Domain Validated SSL,O="thawte, Inc.",C=US
> GET /v1/MossoCloudFS_100/?format=json HTTP/1.1
> User-Agent: curl/7.29.0
> Host: cdn3.clouddrive.com
> Accept: */*
> TOKEN ALTERED FOR SECURITY PURPOSES OF THIS ARTICLE (this token is redacted/altered)
> X-Auth-Token: AAB-bhQKKmZksDz7d93GaV787sesw8RXsQt5_KrzNvAvzRBtfU9uvPzprCXIwMLuN1JrAHjxELYXBPACBOiSo3oak3iRiHZGjuI2wN-JA981cseu3xau3hjzx3uy1hhgZZ32
>
< HTTP/1.1 200 OK
< Content-Length: 2955
< Content-Type: application/json
< X-Trans-Id: txb84c698dab8547178bead-00587cacfelon3
< Date: Mon, 16 Jan 2017 11:22:38 GMT
<
{ [data not shown]
100  2955  100  2955    0     0  19485      0 --:--:-- --:--:-- --:--:-- 19569
* Connection #0 to host cdn3.clouddrive.com left intact
[
    {
        "cdn_enabled": true,
        "cdn_ios_uri": "https://a30ae7cddb38b2112bce-03b08b0e5c91ea60f938585ef20a12d7.iosr.cf3.rackcdn.com",
        "cdn_ssl_uri": "https://1627826b1dc042d6b3be-03b08b0e5c91ea60f938585ef20a12d7.ssl.cf3.rackcdn.com",
        "cdn_streaming_uri": "http://ee7e9298372b91eea2d2-03b08b0e5c91ea60f938585ef20a12d7.r91.stream.cf3.rackcdn.com",
        "cdn_uri": "http://beb2ec8d649b0d717ef9-03b08b0e5c91ea60f938585ef20a12d7.r91.cf3.rackcdn.com",
        "log_retention": false,
        "name": "cdn.site.com",
        "ttl": 86400
    },
    {
        "cdn_enabled": true,
        "cdn_ios_uri": "https://006acc500edc34a84075-1257f240203d0254bc8c5602aafda76dd.iosr.cf3.rackcdn.com",
        "cdn_ssl_uri": "https://b68de0566314da76870d-1257f240203d0254bc8c5602aafda76dd.ssl.cf3.rackcdn.com",
        "cdn_streaming_uri": "http://632bed500bfc691eb677-1257f240203d0254bc8c5602aafda76dd.r49.stream.cf3.rackcdn.com",
        "cdn_uri": "http://b52a6ade17a64c459d85-1257f240203d0254bc8c5602aafda76dd.r49.cf3.rackcdn.com",
        "log_retention": false,
        "name": "container-002",
        "ttl": 604800
    }
]

I only have 2 CDN setup, however if there were more, you'd see all of them too! And, this is pretty much how all your requests can be made to the API. There's many different possibilities. As long as you knew the server UUID of one of your cloud-servers, you could issue a rebuild of the server (rebuild from image), provided you knew the ID of the image you wanted to rebuild..

This is really handy for automation, but also modularity, and interconnecting different parts of your application or workflow with others in ways you might not yet have imagined.

ANOTHER EXAMPLE - rebuilding a cloud-server using the API

So, lets show you how to issue a rebuild server command, providing an additional piece of information that the command needs to run. The API needs to be told, naturally, which cloud-server UUID you are referring to when issuing the comamnd, otherwise it won't know which cloud-server to rebuild!! That's easy, we just provide it in the url! Simples!

#!/bin/bash

# Author: Adam Bull, Rackspace LTD
# Date: January 2017
# Email: adam.bull@rackspace.co.uk
# Use: This is used for rebuilding a cloud-server (defined by supplying the uuid $SERVER_ID) with a reference cloud-server image ImageRef

USERNAME='mycloudusernamegoeshere'
APIKEY='mycloudapikeygoeshere'
ACCOUNT_NUMBER=100
API_ENDPOINT="https://lon.servers.api.rackspacecloud.com/v2/$ACCOUNT_NUMBER"
SERVER_ID='0ed4b86a-71cd-45be-8e90-4c127b851b69'


TOKEN=`curl https://identity.api.rackspacecloud.com/v2.0/tokens -X POST -d '{ "auth":{"RAX-KSKEY:apiKeyCredentials": { "username":"'$USERNAME'", "apiKey": "'$APIKEY'" }} }' -H "Content-type: application/json" |  python -mjson.tool | grep -A5 token | grep id | cut -d '"' -f4`



curl -s -v  \
-H "X-Auth-Token: $TOKEN"  \
-H "X-Project-Id: $ACCOUNT_NUMBER" \
-H "Accept: application/json"  \
-H "Content-Type: application/json" \
-X POST -d '{    "rebuild": {        "imageRef" : "b5a7e8bf-2463-47ba-bf32-d45efaccc21a"   }}' "$API_ENDPOINT/servers/$SERVER_ID/action"| python -mjson.tool

As you can see it's exactly the same as the other requests we made.

THE API ALWAYS WORKS THE SAME - Here's why.

It needs a TOKEN. It provides the Token in a header using -H "X-Auth-Token: $TOKEN"

It also defines the project ID in a header -H "X-Project-Id: $ACCOUNT_NUMBER" .

It is accepting the API to return in JSON, which is defined by using the header -H "Accept: application/json", and a little extra bit in this one, we're providing our own json content in our POST (sending data via HTTP) so we need to say what content-type we're sending, and we need to form an curl -X part of the request to tell the API what on earth it is that we're asking it to do;

-H "Content-Type: application/json" \
-X POST -d '{    "rebuild": {        "imageRef" : "b5a7e8bf-2463-47ba-bf32-d45efaccc21a"   }}' "$API_ENDPOINT/servers/$SERVER_ID/action"| python -mjson.tool