Send API requests to Cloud Databases#

This section shows how to send requests by using either of the following methods:

To learn about other ways to use Rackspace Cloud API services, see the following resources:

Using the trove client#

The trove client is a command-line tool that provides access to all public Cloud Databases API methods. To send requests using the client, you have to install the client and set environment variables.

Prerequisites#

Run the trove client on Linux, the Ubuntu operating sytem, or Debian or Mac OS X. You also need a Rackspace Cloud account and access to Rackspace Cloud Orchestration.

Before you begin, install the following prerequisite software:

Prerequisite

Description

Python 2.7 or later

Currently, the trove client is tested with Python 2.7.

On Mac OS X, run the following command to install Python Homebrew. This command also installs the setuptools and pip packages.

$ brew install python

pip package

To install the trove client on a Mac OS X or Linux system, use pip to ensure that you get the latest version of the trove client from the Python Package Index. You can also use it to update the package later on.

Install pip through the package manager for your system:

Mac OS X

$ sudo easy_install pip

apt get

The Ubuntu operating system, Debian

$ apt-get install python-pip

If the python-pip package is not found, run apt-get update` to update the package list.

yum

Fedora

$ yum install python-pip
CentOS, RHEL*

(from EPEL or another 3rd party repository)

$ yum install python-pip

Install the trove client#

The python-troveclient package contains the trove client.

Run the following commands for your operating system to install the python-troveclient package:

For the Ubuntu operating system or Debian:

$ sudo apt-get install python2.7-dev

$ sudo pip install python-troveclient

For Mac OS X

$ sudo pip install python-troveclient

For RHEL, CentOS, or Fedora:

$ sudo pip install python-troveclient

Note

If you previously installed the python-troveclient package, run the following command to upgrade it:

$ sudo pip install --upgrade python-troveclient

If you installed with apt get or aptitude, re-run the install command to get the latest version of the client.

Configure environment variables for client#

Edit your bash.profile file or .bashrc file to add and set environment variables that enable the trove client to connect to your Rackspace Cloud account. Use nano, or a text editor of your choice, to edit the file.

$ nano ~/.bash_profile

Add the following sets of lines to your bash profile and save the file. Information about the environment variables is provided after the example.

export OS_AUTH_URL=https://identity.api.rackspacecloud.com/v2.0/
export OS_USERNAME=yourUserName
export OS_TENANT_ID=yourTenantId
export OS_REGION_NAME=yourRegionName
export OS_PASSWORD=yourPassword
export TROVE_SERVICE_TYPE=rax:database

The following table describes the environment variables:

Environment variable

Description

OS_USERNAME

Your Rackspace Cloud user name.

OS_PASSWORD

Your Rackspace Cloud password.

OS_PROJECT_ID

Your project ID. In these examples, set it to your Rackspace Cloud account number.

OS_TENANT_ID

Your Rackspace Cloud tenant ID (account number)

TROVE_SERVICE_TYPE

The Rackspace Cloud service name that you want trove client to access. Specify rax:database for Cloud Databases.

OS_AUTH_URL

The endpoint for the Identity service, which the trove client uses for authentication.

OS_REGION_NAME

The regional endpoint (for example, DFW) where you want to deploy the Cloud Databases resources. For details, see Service access endpoints.

After adding the environment variables, complete the following steps to set file permissions and apply the updates.

Set permissions on the bash profile or .bashrc file#

Change the file permissions so that other people cannot steal the password that you included in the file.

$ chmod 600 ~/.bash_profile

Source the environment variables#

To apply the updates to your current shell environment, source the updated file. If you added the environment variables to your bash_profile, run the following command.

$ source ~/.bash_profile

If you set your environment variables in the .bashrc file, run the following command.

$ source ~/.bashrc

Test the client#

To verify that you can talk to the API server, run the following command to authenticate and list flavors:

$ trove flavor-list

Then, list database instances:

$ trove list

Get trove-client help#

Run the following help command to get information about using the trove client.

$ trove help

For a complete list of trove commands, see the OpenStack trove client command-line reference.

Using cURL#

cURL is a command-line tool that you can use to interact with REST interfaces. cURL lets you transmit and receive HTTP requests and responses from the command line or a shell script, which enables you to work with the API directly. cURL is available for Linux distributions, Mac OS® X, and Microsoft Windows®. For information about cURL, see http://curl.haxx.se/.

To run the cURL request examples shown in this guide on Mac OS® X or another Linux-based operating system, copy each example directly to the command line or a script.

Note

If you are using Microsoft Windows, you need to adjust the cURL examples to run them. See Convert cURL examples to run on Windows.

Important

The cURL examples in this guide are provided for reference only. Because the use of cURL has environmental dependencies, copying and pasting the examples might not work in your environment.

The following example shows a cURL command for sending an authentication request to the Identity service.

Example: cURL command for sending a JSON request

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

In this example, $apiKey is an environment variable that stores your API key value. Environment variables make it easier to reference account information in API requests, to reuse the same cURL commands with different credentials, and to keep sensitive information like your API key from being exposed when you send requests to Rackspace Cloud API services. For details about creating environment variables, see Configure environment variables.

Note

The cURL request examples use a backslash (\) as a line-continuation symbol, which allows the command to continue across multiple lines.

The cURL examples in this guide use the following command-line options.

Option

Description

-d

Sends the specified data in a POST request to the HTTP server. Use this option to send a JSON request body to the server.

-H

Specifies an extra HTTP header in the request. You can specify any number of extra headers. Precede each header with the -H option.

Common headers in Rackspace API requests are as follows:

  • Content-Type: Required for operations with a request body.

    Specifies the format of the request body. Following is the syntax for the header where format is json:

    Content-Type: application/json

  • X-Auth-Token: Required. Specifies the authentication token.

  • X-Auth-Project-Id: Optional. Specifies the project ID, which can be your account number or another value.

  • Accept: Optional. Specifies the format of the response body.

    Following is the syntax for the header where the format is json, which is the default:

    Accept: application/json

-i

Includes the HTTP header in the output.

-s

Specifies silent or quiet mode, which makes cURL mute. No progress or error messages are shown.

If your cURL command is not generating any output, try replacing the -s option with -i.

-T

Transfers the specified local file to the remote URL.

-X

Specifies the request method to use when communicating with the HTTP server. The specified method is used instead of the default method, which is GET.

For commands that return a response, you can use json.tool to pretty-print the output. Append the following command to the cURL call:

| python -m json.tool

To use json.tool, import the JSON module. For information about json.tool, see JSON encoder and decoder.

If you run a Python version earlier than 2.6, import the simplejson module and use simplejson.tool. For information about simplejson.tool, see simplejson encoder and decoder.

If you do not want to pretty-print JSON output, omit this code.

Note

If your request includes the -i option to show header output, do not try to pretty-print the output. Header information is not in JSON format, and the API service returns an error if you specify json.tool.

Convert cURL examples to run on Windows#

The cURL examples in the Rackspace API documentation use syntax supported on Mac OS® X, Linux, and UNIX systems. Microsoft Windows does not support the same format. However, you can run the examples on Windows after making the following changes:

  • Replace all the line-continuation backslash characters (\) with a caret (^), and remove any trailing spaces after the ^.

  • If an example includes JSON data, export the data to a text file. When you run the cURL command, use the @filename syntax to import the JSON data. Save the JSON data files in a directory, and run cURL commands from that directory.

The following example shows the cURL format for Linux and UNIX systems:

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

The following example shows the same request with the changes made for Windows systems:

$ curl https://identity.api.rackspacecloud.com/v2.0/tokens  ^
       -X POST ^
       -d @credentials.txt  ^
       -H "Content-type: application/json"