This is the documentation for Cloudera Enterprise 5.8.x. Documentation for other versions is available at Cloudera Documentation.

Configuring and Using the HBase REST API

You can use the HBase REST API to interact with HBase services, tables, and regions using HTTP endpoints.

Installing the REST Server

The HBase REST server is an optional component of HBase and is not installed by default.

    Installing the REST Server Using Cloudera Manager

    Minimum Required Role: Full Administrator

    1. Click the Clusters tab.
    2. Select Clusters > HBase.
    3. Click the Instances tab.
    4. Click Add Role Instance.
    5. Under HBase REST Server, click Select Hosts.
    6. Select one or more hosts to serve the HBase Rest Server role. Click Continue.
    7. Select the HBase Rest Server roles. Click Actions For Selected > Start.
    8. To configure Kerberos authentication between REST clients and servers, see Configure Authentication for the HBase REST and Thrift Gateways.

    Installing the REST Server Using the Command Line

      Important:
    • If you use Cloudera Manager, do not use these command-line instructions.
    • This information applies specifically to CDH 5.8.x. If you use a lower version of CDH, see the documentation for that version located at Cloudera Documentation.

    Follow these instructions for each HBase host fulfilling the REST server role.

    • To start the REST server as a foreground process, use the following command: 
      $ bin/hbase rest start
    • To start the REST server as a background process, use the following command: 
      $ bin/hbase-daemon.sh start rest
    • To use a different port than the default of 8080, use the -p option.
    • To stop a running HBase REST server, use the following command: 
      $ bin/hbase-daemon.sh stop rest
    • To configure Kerberos authentication between REST clients and servers, see Configure Authentication for the HBase REST and Thrift Gateways.

    Using the REST API

    The HBase REST server exposes endpoints that provide CRUD (create, read, update, delete) operations for each HBase process, as well as tables, regions, and namespaces. For a given endpoint, the HTTP verb controls the type of operation (create, read, update, or delete).

      Note: curl Command Examples
    The examples in these tables use the curl command, and follow these guidelines:
    • The HTTP verb is specified using the -X parameter.
    • For GET queries, the Accept header is set to text/xml, which indicates that the client (curl) expects to receive responses formatted in XML. You can set it to text/json to receive JSON responses instead.
    • For PUT, POST, and DELETE queries, the Content-Type header should be set only if data is also being sent with the -d parameter. If set, it should match the format of the data being sent, to enable the REST server to deserialize the data correctly.
    For more details about the curl command, see the documentation for the curl version that ships with your operating system.

    These examples use port 20050, which is the default port for the HBase REST server when you use Cloudera Manager. If you use CDH without Cloudera Manager, the default port for the REST server is 8080.

    Table 1. Cluster-Wide Endpoints
    Endpoint HTTP Verb Description Example
    /version/cluster GET Version of HBase running on this cluster 
    curl -vi -X GET \
         -H "Accept: text/xml" \
         "http://example.com:20550/version/cluster"
    /status/cluster GET Cluster status 
    curl -vi -X GET \
         -H "Accept: text/xml" \
         "http://example.com:20550/status/cluster"
    / GET List of all nonsystem tables 
    curl -vi -X GET \
         -H "Accept: text/xml" \
         "http://example.com:20550/"
    Table 2. Namespace Endpoints
    Endpoint HTTP Verb Description Example
    /namespaces GET List all namespaces. 
    curl -vi -X GET \
         -H "Accept: text/xml" \
         "http://example.com:20550/namespaces/"
    /namespaces/namespace GET Describe a specific namespace. 
    curl -vi -X GET \
         -H "Accept: text/xml" \
         "http://example.com:20550/namespaces/special_ns"
    /namespaces/namespace POST Create a new namespace. 
    curl -vi -X POST \
         -H "Accept: text/xml" \
         "example.com:20550/namespaces/special_ns"
    /namespaces/namespace/tables GET List all tables in a specific namespace. 
    curl -vi -X GET \
         -H "Accept: text/xml" \
         "http://example.com:20550/namespaces/special_ns/tables"
    /namespaces/namespace PUT Alter an existing namespace. Currently not used. 
    curl -vi -X PUT \
         -H "Accept: text/xml" \
         "http://example.com:20550/namespaces/special_ns"
    /namespaces/namespace DELETE Delete a namespace. The namespace must be empty. 
    curl -vi -X DELETE \
         -H "Accept: text/xml" \
         "example.com:20550/namespaces/special_ns"
    Table 3. Table Endpoints
    Endpoint HTTP Verb Description Example
    /table/schema GET Describe the schema of the specified table. 
    curl -vi -X GET \
         -H "Accept: text/xml" \
         "http://example.com:20550/users/schema"
    /table/schema POST Create a new table, or replace an existing table's schema with the provided schema 
    curl -vi -X POST \
         -H "Accept: text/xml" \
         -H "Content-Type: text/xml" \
         -d '<?xml version="1.0" encoding="UTF-8"?><TableSchema name="users"><ColumnSchema name="cf" /></TableSchema>' \
         "http://example.com:20550/users/schema"
    /table/schema UPDATE Update an existing table with the provided schema fragment 
    curl -vi -X PUT \
         -H "Accept: text/xml" \
         -H "Content-Type: text/xml" \
         -d '<?xml version="1.0" encoding="UTF-8"?><TableSchema name="users"><ColumnSchema name="cf" KEEP_DELETED_CELLS="true" /></TableSchema>' \
         "http://example.com:20550/users/schema"
    /table/schema DELETE Delete the table. You must use the table/schema endpoint, not just table/. 
    curl -vi -X DELETE \
         -H "Accept: text/xml" \
         "http://example.com:20550/users/schema"
    /table/regions GET List the table regions. 
    curl -vi -X GET \
         -H "Accept: text/xml" \
         "http://example.com:20550/users/regions"
    Table 4. Endpoints for Get Operations
    Endpoint HTTP Verb Description Example
    /table/row/column:qualifier/timestamp GET Get the value of a single row. Values are Base-64 encoded. Latest version: 
    curl -vi -X GET \
         -H "Accept: text/xml" \
         "http://example.com:20550/users/row1"
    Specific timestamp: 
    curl -vi -X GET \
         -H "Accept: text/xml" \
         "http://example.com:20550/users/row1/cf:a/1458586888395"
        Get the value of a single column. Values are Base-64 encoded. Latest version: 
    curl -vi -X GET \
         -H "Accept: text/xml" \
         "http://example.com:20550/users/row1/cf:a"
    Specific version: 
    curl -vi -X GET \
         -H "Accept: text/xml" \
          "http://example.com:20550/users/row1/cf:a/"
    /table/row/column:qualifier?v=number_of_versions   Multi-Get a specified number of versions of a given cell. Values are Base-64 encoded. 
    curl -vi -X GET \
         -H "Accept: text/xml" \
         "http://example.com:20550/users/row1/cf:a?v=2"
    Table 5. Endpoints for Scan Operations
    Endpoint HTTP Verb Description Example
    /table/scanner/ PUT Get a Scanner object. Required by all other Scan operations. Adjust the batch parameter to the number of rows the scan should return in a batch. See the next example for adding filters to your Scanner. The scanner endpoint URL is returned as the Location in the HTTP response. The other examples in this table assume that the Scanner endpoint is http://example.com:20550/users/scanner/145869072824375522207. 
    curl -vi -X PUT \
         -H "Accept: text/xml" \
         -H "Content-Type: text/xml" \
         -d '<Scanner batch="1"/>' \
         "http://example.com:20550/users/scanner/"
    /table/scanner/ PUT To supply filters to the Scanner object or configure the Scanner in any other way, you can create a text file and add your filter to the file. For example, to return only rows for which keys start with u123 and use a batch size of 100: 
    <Scanner batch="100">
  <filter>
    {
      "type": "PrefixFilter",
      "value": "u123"
    }
  </filter>
</Scanner>
    Pass the file to the -d argument of the curl request.    		 
    curl -vi -X PUT \
         -H "Accept: text/xml" \
         -H "Content-Type:text/xml" \
         -d @filter.txt \
         "http://example.com:20550/users/scanner/"
    /table/scanner/scanner_id GET Get the next batch from the scanner. Cell values are byte-encoded. If the scanner is exhausted, HTTP status 204 is returned. 
    curl -vi -X GET \
         -H "Accept: text/xml" \
         "http://example.com:20550/users/scanner/145869072824375522207"
    /table/scanner/scanner_id DELETE Deletes the scanner and frees the resources it was using. 
    curl -vi -X DELETE \
         -H "Accept: text/xml" \
         "http://example.com:20550/users/scanner/145869072824375522207"
    Table 6. Endpoints for Put Operations
    Endpoint HTTP Verb Description Example
    /table/row_key/ PUT Write a row to a table. The row, column qualifier, and value must each be Base-64 encoded. To encode a string, you can use the base64 command-line utility. To decode the string, use base64 -d. The payload is in the --data argument, so the /users/fakerow value is a placeholder. Insert multiple rows by adding them to the <CellSet> element. You can also save the data to be inserted to a file and pass it to the -d parameter with the syntax -d @filename.txt. XML: 
    curl -vi -X PUT \
         -H "Accept: text/xml" \
         -H "Content-Type: text/xml" \
         -d '<?xml version="1.0" encoding="UTF-8" standalone="yes"?><CellSet><Row key="cm93NQo="><Cell column="Y2Y6ZQo=">dmFsdWU1Cg==</Cell></Row></CellSet>' \
         "http://example.com:20550/users/fakerow"
    JSON: 
    curl -vi -X PUT \
         -H "Accept: text/json" \
         -H "Content-Type: text/json" \
         -d '{"Row":[{"key":"cm93NQo=", "Cell": [{"column":"Y2Y6ZQo=", "$":"dmFsdWU1Cg=="}]}]}'' \
         "example.com:20550/users/fakerow"
    Page generated July 8, 2016.