Ambari API Reference v1

The Ambari API provides access to monitoring and metrics information of a Apache Hadoop cluster. This document describes the resources used in the Ambari API and is intended for developers who want to integrate with Ambari.

• Release Version
• Authentication
• Resources
• Partial Response
• Query Parameters
• Errors

Release Version

Last Updated December 28, 2012

Authentication

The operations you perform against the Ambari API require authentication. Your access to the API requires the use of Basic Authentication. To use Basic Authentication, you need to send the Authorization: Basic header with your requests. For example, this can be handled when using curl and the --user option.

curl --user name:password http://{your.ambari.server}/api/v1/clusters

Note: The authentication method and source is configured at the Ambari Server. Changing and configuring the authentication method and source is not covered in this document.

Resources

There are 2 types of resources in the Ambari API:

• Collection Resource: This resource type refers to a collection of resources, rather than any specific resource. For example:

    /clusters  
  

  Returns a collection of clusters

• Instance Resource: This resource type refers to a single specific resource. For example:

    /clusters/MyCluster
  

  Refers to the cluster resource identified by the id “MyCluster”

Clusters

• List clusters
• View cluster information

Services

• List services
• View service information
• View service components
• View component information

Hosts

• List hosts
• View host information
• List host components
• View host component information

Partial Response

A mechanism used to control which fields are returned by a query. Partial response can be used to restrict which fields are returned and additionally, it allows a query to reach down and return data from sub-resources. The keyword “fields” is used to specify a partial response. Only the fields listed will be returned to the client. To specify sub-elements, use the notation “a/b/c”. The wildcard ‘*’ can be used to show all fields for a resource. This can be combined to provide ‘expand’ functionality for sub-components. Some fields are always returned for a resource regardless of the specified partial response fields. These fields are the fields which uniquely identify the resource. This would be the primary id field of the resource and the foreign keys to the primary id fields of all ancestors of the resource.

*Example: Partial Response (Name and All metrics)

GET    /api/v1/clusters/MyCluster/services/HDFS/components/NAMENODE?fields=name,metrics


200 OK
{
  “href” :”.../api/v1/clusters/MyCluster/services/HDFS/components/NAMENODE?fields=name,metrics”,
  “name”: “NAMENODE”,
  “metrics”: [
    {
    ...
    }
  ]
}

Query Parameters

This mechanism limits which data is returned by a query based on a predicate(s). Providing query parameters does not result in any link expansion in the data that is returned to the client although it may result in expansion on the server to apply predicates on sub-objects.

Note: Only applies to collection resources. And all URLs must be properly URL encoded

Query Operators

Example: Get all hosts with less than 100 “disk_total”

GET  /api/v1/clusters/c1/hosts?metrics/disk/disk_total<100

Errors

This section describes how errors are represented in a response.

Response

404 Not Found
{
  “status”: 404,
  “message”: “standard message”,
  “developerMessage”: “verbose developers message”,
  “code”: 1234,
  “moreInfo”, “...”
}