Using the Ambari REST API

You can monitor and manage the resources in your HAWQ cluster using the Ambari REST API. In addition to providing access to the metrics information in your cluster, the API supports viewing, creating, deleting, and updating cluster resources.

This section will provide an introduction to using the Ambari REST APIs for HAWQ-related cluster management activities.

Refer to Ambari API Reference v1 for the official Ambari API documentation, including full REST resource definitions and response semantics. Note: These APIs may change in new versions of Ambari.

Manageable HAWQ Resources

HAWQ provides several REST resources to support starting and stopping services, executing service checks, and viewing configuration information among other activities. HAWQ resources you can manage using the Ambari REST API include:

URI Structure

The Ambari REST API provides access to HAWQ cluster resources via URI (uniform resource identifier) paths. To use the Ambari REST API, you will send HTTP requests and parse JSON-formatted HTTP responses.

The Ambari REST API supports standard HTTP request methods including:

• GET - read resource properties, metrics
• POST - create new resource
• PUT - update resource
• DELETE - delete resource (use with care)

Note: Be careful when using DELETE or PUT requests; typos or other incorrect usage may leave your cluster in an inoperable state.

URIs for Ambari REST API resources have the following structure:

http://<ambari-server-host>:<port>/api/v1/<resource-path>

The Ambari REST API supports the following HAWQ-related <resource-paths>:

Submitting Requests with cURL

Your HTTP request to the Ambari REST API should include the following information:

• User name and password for basic authentication.
• An HTTP request header.
• The HTTP request method.
• JSON-formatted request data, if required.
• The URI identifying the Ambari REST resource.

You can use the curl command to transfer HTTP request data to, and receive data from, the Ambari server using the HTTP protocol.

Use the following syntax to issue a curl command for Ambari HAWQ/PXF management operations:

$ curl -u <user>:<passwd> -H <header> -X GET|POST|PUT|DELETE -d <data> <URI>

curl options relevant to Ambari REST API communication include:

Authenticating with the Ambari REST API

The first step in using the Ambari REST API is to authenticate with the Ambari server. The Ambari REST API supports HTTP basic authentication. With this authentication method, you provide a username and password that is internally encoded and sent in the HTTP header.

Example: Testing Authentication

1. Set up some environment variables; replace the values with those appropriate for your operating environment. For example:

   $ export AMBARI_USER=admin
   $ export AMBARI_PASSWD=admin
   $ export AMBARI_HOST=<ambari-server>
   $ export AMBARI_PORT=8080
   

2. Submit a curl request to the Ambari server:

   $ curl -u $AMBARI_USER:$AMBARI_PASSWD http://$AMBARI_HOST:$AMBARI_PORT
   

   If authentication succeeds, Apache license information is displayed.

Using the Ambari REST API for HAWQ Management

Example: Retrieving the HAWQ Cluster Name

1. Set up an additional environment variables:

   $ export AMBARI_CREDS="$AMBARI_USER:$AMBARI_PASSWD"
   $ export AMBARI_URLBASE="http://${AMBARI_HOST}:${AMBARI_PORT}/api/v1/clusters"
   

   You will use these variables in upcoming examples to simplify curl calls.

2. Use the Ambari REST API to determine the name of your HAWQ cluster; also set $AMBARI_URLBASE to include the cluster name:

   $ export CLUSTER_NAME="$(curl -u ${AMBARI_CREDS} -i -H 'X-Requested-By:ambari' $AMBARI_URLBASE | sed -n 's/.*"cluster_name" : "\([^\"]*\)".*/\1/p')"
   $ echo $CLUSTER_NAME
   TestCluster
   $ export AMBARI_URLBASE=$AMBARI_URLBASE/$CLUSTER_NAME
   

Examples: Managing the HAWQ and PXF Services

The following subsections provide curl commands for common HAWQ cluster management activities.

Refer to API usage scenarios, troubleshooting, and other FAQs for additional Ambari REST API usage examples.

Viewing HAWQ Cluster Service and Configuration Information

Starting/Stopping HAWQ and PXF Services

Invoking HAWQ and PXF Service Actions