Send API requests to Rackspace Monitoring

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.

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

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:

1. Log in to a bash shell on your local workstation as the user who has write permissions to /usr/local/bin.

2. 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.

1. To remove the existing version, run the following command:

   $ sudo pip uninstall rackspace-monitoring-cli

2. 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.

1. If you do not already have your API key, follow the instructions in Get your credentials

2. 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

3. 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