Difference between revisions of "Rackspace API"

Revision as of 20:20, 27 December 2013

This article will be a somewhat random assortment of API calls to various Rackspace services. I plan to organize this article and add nearly all possible calls. Most of the API calls will be made using `curl` commands, but other resources will be used as well.

Environment variables

Note: This is probably not the most secure way to store your account username, API Key, account number, or token. However, it makes it simpler to illustrate using the Rackspace API in this article.

You can find all of the following (except for your 24-hour-valid token) in the Rackspace Cloud Control Panel under the "Account Settings" section.

MYRAXUSERNAME=your_account_username
MYRAXAPIKEY=your_unique_api_key  # _never_ give this out to anyone!
MYRAXACCOUNT=integer_value  # e.g., 123456
MYRAXTOKEN=your_24_hour_valid_token  # see below

I will be using the above environment variables for the remainder of this article.

Regions

The following are the Rackspace API endpoint regions (aka the data centres where your servers/data live):

• DFW - Dallas DC
• HKG - Hong Kong DC
• IAD - Norther Virginia DC
• LON - London DC
• ORD - Chicago DC
• SYD - Sydney DC

Authentication

For every API call it is first necessary to obtain an authenticated token. These tokens are valid for 24 hours and you must re-authenticate if it has expired. To authenticate, you only need your Rackspace account username ($MYRAXUSERNAME) and your API Key ($MYRAXAPIKEY).

• Simple authentication (this should return, among other things, an "X-Auth-Token"):

curl -D - -H "X-Auth-Key: $MYRAXAPIKEY" \
     -H "X-Auth-User: $MYRAXUSERNAME" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     https://identity.api.rackspacecloud.com/v1.0

• Authenticate the same way as above, but time namelookup, connect, starttransfer, and total API calls:

curl -D - -H "X-Auth-Key: $MYRAXAPIKEY" \
     -H "X-Auth-User: $MYRAXUSERNAME" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -w "time_namelookup: %{time_namelookup}\ntime_connect: %{time_connect}\ntime_starttransfer: %{time_starttransfer}\ntime_total: %{time_total}\n" \
     https://identity.api.rackspacecloud.com/v1.0

• Authenticate and receive a full listing of API endpoints (for all of the Rackspace services active on your account):

curl -X POST https://identity.api.rackspacecloud.com/v2.0/tokens \
     -d '{ "auth":{ "RAX-KSKEY:apiKeyCredentials":{ "username":"'$MYRAXUSERNAME'", "apiKey":"'$MYRAXAPIKEY'" } } }' \
     -H "Content-type: application/json"

• Authenticate the same way as above, but use compression during the send/receive:

curl -i -X POST \
     -H 'Host: identity.api.rackspacecloud.com' \
     -H 'Accept-Encoding: gzip,deflate' \
     -H 'X-LC-Request-ID: 16491440' \
     -H 'Content-Type: application/json; charset=UTF-8' \
     -H 'Content-Length: 119' \
     -H 'Accept: application/json' \
     -H 'User-Agent: libcloud/0.13.0 (Rackspace Monitoring)' \
     --data-binary '{"auth": {"RAX-KSKEY:apiKeyCredentials": {"username": "$MYRAXUSERNAME", "apiKey": "$MYRAXAPIKEY"}}}' \
     --compress https://identity.api.rackspacecloud.com:443/v2.0/tokens

• Save the "X-Auth-Token" as an environmental variable (remember, this token will only be valid for 24 hours):

MYRAXTOKEN=`curl -s -XPOST https://identity.api.rackspacecloud.com/v2.0/tokens \
  -d'{"auth":{"RAX-KSKEY:apiKeyCredentials":{"username":"'$MYRAXUSERNAME'","apiKey":"'$MYRAXAPIKEY'"}}}' \
  -H"Content-type:application/json" | \
  python -c 'import sys,json;data=json.loads(sys.stdin.read());print data["access"]["token"]["id"]'`

I will use this $MYRAXTOKEN environment variable (from the last command) for the remainder of this article.

Cloud Servers

Note: See the NextGen API docs or the FirstGen API docs for more details and examples. Take note of the API version numbers (e.g., "v1.0", "v2", etc.), as they are important and some are deprecated.

• List all of the NextGen servers on your account for a given region:

REGION=dfw
curl -XGET https://${REGION}.servers.api.rackspacecloud.com/v2/${MYRAXACCOUNT}/servers \
     -H "X-Auth-Token: ${MYRAXTOKEN}" \
     -H "Accept: application/json" | python -m json.tool

• List all of the FirstGen servers on your account (regardless of region):

curl -s https://servers.api.rackspacecloud.com/v1.0/${MYRAXACCOUNT}/servers \
     -H "X-Auth-Token: ${MYRAXTOKEN}" | python -m json.tool

• Create a NextGen Cloud Server (in your account's default region):

curl -s https://servers.api.rackspacecloud.com/v1.0/${MYRAXACCOUNT}/servers -X POST \
    -H "Content-Type: application/json" \
    -H "X-Auth-Token: ${MYRAXTOKEN}" \
    -d "{\"server\":{\"name\":\"testing\",\"imageId\":12345678,\"flavorId\":4,}}" | python -m json.tool

The above should return something similar to the following (note that "status": "BUILD" will become "Active" once the build process is complete):

{
    "server": {
    "addresses": {
    "private": [
    "10.x.x.x"
    ],
    "public": [
    "184.x.x.x"
    ]
},
"adminPass": "lR2aB3g5Xtesting",
"flavorId": 4,
"hostId": "ffffff2cd2470205bbe2f6b6f7f83d14",
"id": 87654321,
"imageId": 12345678,
"metadata": {},
"name": "testing",
"progress": 0,
"status": "BUILD"
}
}

• Delete a Cloud Server:

$ curl -i -X DELETE -H "X-Auth-Token: ${MYRAXTOKEN}" \
       https://${REGION}.servers.api.rackspacecloud.com/v2/${MYRAXACCOUNT}/servers/${SERVER_ID}

• Resize (up/down) a Cloud Server (see: for details):

$ curl -i -vv -X POST \
       -H "X-Auth-Token: ${MYRAXTOKEN}" -H "Content-Type: application/json" \
       https://${REGION}.servers.api.rackspacecloud.com/v2/${MYRAXACCOUNT}/servers/${SERVER_ID}/action \
       -d '{"resize":{"flavorRef":"2"}}'

• Change administrative password (see: for details)

$ curl -v -s -XPUT https://servers.api.rackspacecloud.com/v1.0/${MYRAXACCOUNT}/servers/${SERVER_ID} \
       -H "Accept: application/json" -H "Content-Type: application/json" -H "X-Auth-Token: ${MYRAXTOKEN}" \
       -d '{"server":{"name":"SERVER_NAME", "adminPass": "NEW_PASSWORD"}}'
# Normal Response Code: 204

Cloud Files

Note: See the Cloud Files docs for more details and examples.

• Create container (e.g., region DFW):

$ REGION=dfw; curl -XPUT -H "X-Auth-Token: $MYRAXTOKEN" \
  https://storage101.${REGION}1.clouddrive.com/v1/MossoCloudFS_ffff-ffff-ffff-ffff-ffff/container_name

Note: If you are always going to create containers (and put objects) in the same data centre/region (e.g., DFW), you can shorten your `curl` command like so:

$ ENDPOINT_URL=https://storage101.dfw1.clouddrive.com/v1/MossoCloudFS_ffff-ffff-ffff-ffff-ffff
$ curl -XPUT -H "X-Auth-Token: $MYRAXTOKEN" "${ENDPOINT_URL}/${CONTAINER}"

Your API URL endpoint will be identical for all regions (except for the "dfw", "ord", etc. part). As such, I will use that "ENDPOINT_URL" for the remaining examples in this Cloud Files section.

• Upload ("PUT") a file to a given container:

$ CONTAINER=foo; curl -X PUT -T /path/to/your/local/file.txt -D - \
   -H "Content-Type: text/plain" \
   -H "X-Auth-Token: ${MYRAXTOKEN}" \
   -H "X-Object-Meta-Screenie: Testing PUT Object" \
   "${ENDPOINT_URL}/{$CONTAINER}/file.txt"
HTTP/1.1 100 Continue
HTTP/1.1 201 Created
Last-Modified: Fri, 27 Dec 2013 19:53:35 GMT
Content-Length: 0
Etag: d41d8cd98fdfeg5fe9800998ecf8427e
Content-Type: text/html; charset=UTF-8
X-Trans-Id: txfffffffffffffffffffff-ffffffffffdfw1
Date: Fri, 27 Dec 2013 19:53:35 GMT

Note: If you do not explicitly define the "Content-Type" header, the API will try to guess the object type. If it can not guess which type the object you are uploading is, it will probably set it as "application/octet-stream".

• Download ("GET") an object ("file") from a given container:

$ CONTAINER=foo; curl -X GET -o /path/where/to/download/file.txt "${ENDPOINT_URL}/{$CONTAINER}/file.txt" -H "X-Auth-Token: ${MYRAXTOKEN}"

Note: You do not have to include the "-X GET" in the above command, since that is the default request in `code`. However, I like to include it, as it makes it very clear (to me, my log files, my HISTORY, etc.) what I was requesting.

• List all containers in a given region (note: the "-D -" dumps the header response to STDOUT. You can remove that part if you do not need/want it):

$ REGION=dfw; curl -X GET -D - -H "X-Auth-Token:${MYRAXTOKEN}" "${ENDPOINT_URL}"

• Controlling a large list of containers (i.e., pagination; see: for details).

If you have hundreds or thousands of containers in your Cloud Files, you may not want/need to list them all out (as in the previous example). This is where setting limits, markers, and offsets (aka "pagination") becomes useful. (Note: The maximum list of containers the API will return is 10,000. Therefore, you must use pagination if you have more than that and wish to list them all.)

For an example, say you have the following Cloud Files containers:

foo
bar
baz
qux

To list only the first two (i.e., "foo" and "bar"), use the "?limit=2" parameter, like so:

$ curl -X GET -D - -H "X-Auth-Token:${MYRAXTOKEN}" "${ENDPOINT_URL}/?limit=2"
foo
bar

To list the next two containers (i.e., "baz" and "qux"), use the last container name from the previous command as the "marker" in the following command:

$ LIMIT=2; MAKER=bar; curl -X GET -D - -H "X-Auth-Token:${MYRAXTOKEN}" "${ENDPOINT_URL}/?limit=${LIMIT}&marker=${MARKER}"
baz
qux

• Get information on a given container (e.g., list of objects, the timestamp of when the container was created, bytes used, metadata, etc.; see: here for information on how to set/update metadata):

$ CONTAINER=foo; curl -I "${ENDPOINT_URL}/${CONTAINER}" -H "X-Auth-Token:${MYRAXTOKEN}"
HTTP/1.1 204 No Content
Content-Length: 0
X-Container-Object-Count: 21
Accept-Ranges: bytes
X-Container-Meta-Access-Log-Delivery: false
X-Timestamp: 1369387765.22382
X-Container-Bytes-Used: 10655668
Content-Type: text/plain; charset=utf-8
X-Trans-Id: txfffffffffffffffffffff-ffffffffffdfw1
Date: Fri, 27 Dec 2013 18:40:32 GMT

A status code of 204 (No Content) indicates success. Status code 404 (Not Found) is returned when the requested container does not exist.

So, the container named "foo" has 21 objects in it and they are using 10655668 bytes (~10.66 MB) of space. Note that the "X-Trans-Id: txfffffffffffffffffffff-ffffffffffdfw1" also tells you which data centre this container is stored in (i.e., the "dfw1" characters at the end of that string). Of course, you already knew that, as you told it which DC to use in your `curl` command (however, that might be useful information to store in, say, log files).

The container was created in Unix/POSIX time (UTC) on "1369387765.22382" (i.e., 2013-05-24 04:29:25.223820 in local time). You can use the following Python code to translate from a Unix timestamp to your local time:

>>> print datetime.datetime.fromtimestamp(1369387765.22382)
2013-05-24 04:29:25.223820

You can also get information on a given object ("file") within a given container:

$ CONTAINER=foo; curl -I "${ENDPOINT_URL}/${CONTAINER}/testfile2" -H "X-Auth-Token:${MYRAXTOKEN}"
HTTP/1.1 200 OK
Content-Length: 0
Accept-Ranges: bytes
Last-Modified: Fri, 27 Dec 2013 19:59:42 GMT
Etag: d41d8cd98fd34fscfe9800998ecf8427e
X-Timestamp: 1388174382.97599
Content-Type: text/plain
X-Object-Meta-Screenie: Testing PUT Object
X-Trans-Id: txfffffffffffffffffffff-ffffffffffdfw1
Date: Fri, 27 Dec 2013 19:59:56 GMT

Note that the "X-Object-Meta-Screenie" header was set in the previous upload/put object example (see above).

External links

• Rackspace API Documentation