Send API requests to Rackspace Monitoring

This Getting Started Guide shows how to send requests by using either of the following methods:

Using cURL

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

If you are developing applications or automation, see OpenStack client applications.

For API development, testing and workflow management in a graphical environment, try interacting with the API by using an application such as Postman or RESTClient for Firefox.

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 indicates that the command continues 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"

Using the raxmon client

The Rackspace Monitoring command-line interface (CLI), known as raxmon, lets you interact with the Rackspace Monitoring API in a quick and efficient manner. If you’re not a programmer, consider using raxmon to become familiar with the product and its capabilities. Even if you have programming experience, you might like the speed at which you can set up monitors by using the Rackspace Monitoring client.

You can use the client for this tutorial by installing and running it from local workstation, not on the servers that you plan to monitor.

Note

Raxmon is not designed to work on a Windows OS.

Prerequisites for using raxmon

Prerequisites for nova clients

Linux or Mac OS X
Python 2.6 or later
setuptools package, installed by default on Mac OS X
pip package
Rackspace Cloud account and access to Rackspace Monitoring

Prerequisite	Description
Python 2.5, 2.6, or 2.7	Currently, the raxmon client does not support Python 3.
setuptools package	Installed by default on Mac OS X. Many Linux distributions provide packages to make setuptools easy to install. Search your package manager for setuptools to find an installation package. If you cannot find one, download the setuptools package directly from http://pypi.python.org/pypi/setuptools.
pip package	To install the nova client on a Mac OS X or Linux system, use pip because it is easy and ensures that you get the latest version of the nova client from the Python Package Index at http://pypi.python.org/pypi/python-novaclient/>. Also, it lets you update the package later on. Install pip through the package manager for your system: Mac OS X $ sudo easy_install pip The Ubuntu operating system $ aptitude install python-pip Debian $ aptitude install python-pip Fedora $ yum install python-pip * CentOS, or RHEL (from EPEL or another 3rd party repository) $ yum install python-pip

Note

Raxmon is not designed to work on a Windows OS. The tutorial assumes you have a Mac OS.

Installing the client

Follow these steps to install raxmon on your local workstation if you don’t already have a version installed.

If you have an earlier version installed, upgrade to version 0.4.6 or later. See the Rackspace Monitoring CLI GitHub repository for the most current version.

Before you install raxmon, you must have Python version 2.5, 2.6, or 2.7 installed on your local computer (the computer on which you will install raxmon).

Important

Raxmon is not supported on a Windows OS.

To install the Rackspace monitoring client, complete the following steps:

Log in to a bash shell on your local workstation as the user who has write permissions to /usr/local/bin.
To install the client, run the following command: .. code:

$ sudo pip install rackspace-monitoring-cli

Upgrading the client

If you have an earlier version of Rackspace Monitoring client installed, complete the following steps to upgrade to version 0.4.6 or later.

To remove the existing version, run the following command:

$ sudo pip uninstall rackspace-monitoring-cli
To upgrade to the latest version, run the following command:

$ sudo pip install --upgrade rackspace-monitoring-cli

Configuring the client

Although you can specify your Rackspace credentials and URLs as command-line options, it saves time to add them to the Rackspace Monitoring client configuration file.

Complete the following steps to configure the client with your credentials and the URLs for Rackspace Monitoring and the Identity service.

If you do not already have your API key, follow the instructions in Get your credentials
Using vi or your favorite text editor, open the .raxrc file in your home directory. Following is an example of the vi command to open the file.

$ vi ~/.raxrc
Edit the file to specify your Rackspace username and API key, and the Identity endpoint for your account. Following is an example of the .raxrc file with Rackspace credentials and URLs:

[credentials]
username=MyRackspaceAcct
api_key=0000000000000000000

[api]
url=https://monitoring.api.rackspacecloud.com/v1.0

[auth_api]
url=https://identity.api.rackspacecloud.com/v2.0/tokens

[ssl]
verify=true

Using raxmon

After you have installed raxmon, type the following command in a terminal or command window to see a list of the available raxmon commands:

raxmon --h

To get help for a particular command, type the following command, replacing italicized text:

raxmon-command-name –h

For example, to see a brief description of each option that you would use to create an entity in the monitoring system, type the following command:

raxmon-entities-create --h