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

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

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

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.

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/"
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 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"
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"
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"
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"