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.

Background

For a given endpoint, the HTTP verb controls the following type of operations (create, read, update, or delete).

In CDP, all REST queries are routed through the Apache Knox gateway. In your REST query, ensure that the hostname points to the gateway node and cdp-proxy-api endpoint as shown in these examples.

Table 1. Cluster-Wide Endpoints
Endpoint HTTP Verb Description Example
/version/cluster GET Version of HBase running on this cluster
curl -L -v \
-u "<MY_WORKLOAD_USERNAME:MY_WORKLOAD_PASSWORD>" \
"https://<gateway_node>/cdp-proxy-api/hbase/version/cluster"
/status/cluster GET Cluster status
curl -vi -X GET \
-H "Accept: text/xml" \      
-u "<MY_WORKLOAD_USERNAME:MY_WORKLOAD_PASSWORD>" \
"https://<gateway_node>/cdp-proxy-api/hbase/status/cluster"
/ GET List of all nonsystem tables
curl -vi -X GET \
-H "Accept: text/xml" \
-u "<MY_WORKLOAD_USERNAME:MY_WORKLOAD_PASSWORD>" \
"https://<gateway_node>/cdp-proxy-api/hbase"
Table 2. Namespace Endpoints
Endpoint HTTP Verb Description Example
/namespaces GET List all namespaces.
curl -vi -X GET \
-H "Accept: text/xml" \
-u "<MY_WORKLOAD_USERNAME:MY_WORKLOAD_PASSWORD>" \
"https://<gateway_node>/cdp-proxy-api/hbase/namespaces/" 
/namespaces/namespace GET Describe a specific namespace.
curl -vi -X GET \
-H "Accept: text/xml" \
-u "<MY_WORKLOAD_USERNAME:MY_WORKLOAD_PASSWORD>" \
"https://<gateway_node>/cdp-proxy-api/hbase/namespaces/special_ns"
/namespaces/namespace POST Create a new namespace.
curl -vi -X POST \
-H "Accept: text/xml" \
-u "<MY_WORKLOAD_USERNAME:MY_WORKLOAD_PASSWORD>" \
"https://<gateway_node>/cdp-proxy-api/hbase/namespaces/special_ns"
/namespaces/namespace/tables GET List all tables in a specific namespace.
curl -vi -X GET \
-H "Accept: text/xml" \
-u "<MY_WORKLOAD_USERNAME:MY_WORKLOAD_PASSWORD>" \
"https://<gateway_node>/cdp-proxy-api/hbase/namespaces/special_ns/tables" 
/namespaces/namespace PUT Alter an existing namespace. Currently not used.
curl -vi -X PUT \
-H "Accept: text/xml" \
-u "<MY_WORKLOAD_USERNAME:MY_WORKLOAD_PASSWORD>" \
"https://<gateway_node>/cdp-proxy-api/hbase/namespaces/special_ns"
/namespaces/namespace DELETE Delete a namespace. The namespace must be empty.
curl -vi -X DELETE \
-H "Accept: text/xml" \
-u "<MY_WORKLOAD_USERNAME:MY_WORKLOAD_PASSWORD>" \
"https://<gateway_node>/cdp-proxy-api/hbase/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" \
-u "<MY_WORKLOAD_USERNAME:MY_WORKLOAD_PASSWORD>" \
"https://<gateway_node>/cdp-proxy-api/hbase/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>' \
-u "<MY_WORKLOAD_USERNAME:MY_WORKLOAD_PASSWORD>" \
"https://<gateway_node>/cdp-proxy-api/hbase/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>' \
-u "<MY_WORKLOAD_USERNAME:MY_WORKLOAD_PASSWORD>" \
"https://<gateway_node>/cdp-proxy-api/hbase/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" \
-u "<MY_WORKLOAD_USERNAME:MY_WORKLOAD_PASSWORD>" \
"https://<gateway_node>/cdp-proxy-api/hbase/users/schema" 
/table/regions GET List the table regions.
curl -vi -X GET \
-H "Accept: text/xml" \
-u "<MY_WORKLOAD_USERNAME:MY_WORKLOAD_PASSWORD>" \
"https://<gateway_node>/cdp-proxy-api/hbase/users/schema" 
Table 4. Endpoints for Get Operations
Endpoint HTTP Verb Description Example
/table/row GET Get all columns of a single row. Values are Base-64 encoded. This requires the Accept request header with a type that can hold multiple columns (like xml, json or protobuf)
curl -vi -X GET \
  -H "Accept: text/xml" \
 -u "<MY_WORKLOAD_USERNAME:MY_WORKLOAD_PASSWORD>" \ "https://<gateway_node>/cdp-proxy-api/hbase/users/row1"
/table/row/column:qualifier/timestamp GET Get the value of a single row. Values are Base-64 encoded.
curl -vi -X GET \
  -H "Accept: text/xml" \
 -u "<MY_WORKLOAD_USERNAME:MY_WORKLOAD_PASSWORD>" \ "https://<gateway_node>/cdp-proxy-api/hbase/users/row1/cf:a/1458586888395"
/table/row/column:qualifier GET Get the value of a single column. Values are Base-64 encoded.
curl -vi -X GET \
  -H "Accept: text/xml" \
 -u "<MY_WORKLOAD_USERNAME:MY_WORKLOAD_PASSWORD>" \ "https://<gateway_node>/cdp-proxy-api/hbase/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" \
 -u "<MY_WORKLOAD_USERNAME:MY_WORKLOAD_PASSWORD>" \ "https://<gateway_node>/cdp-proxy-api/hbase/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"/>' \
-u "<MY_WORKLOAD_USERNAME:MY_WORKLOAD_PASSWORD>" \
"https://<gateway_node>/cdp-proxy-api/hbase/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 \
-u "<MY_WORKLOAD_USERNAME:MY_WORKLOAD_PASSWORD>" \
"https://<gateway_node>/cdp-proxy-api/hbase/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" \
"<MY_WORKLOAD_USERNAME:MY_WORKLOAD_PASSWORD>" \
-u "https://<gateway_node>/cdp-proxy-api/hbase/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" \
-u "<MY_WORKLOAD_USERNAME:MY_WORKLOAD_PASSWORD>" \
"https://<gateway_node>/cdp-proxy-api/hbase/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>' \
-u "<MY_WORKLOAD_USERNAME:MY_WORKLOAD_PASSWORD>" \
"https://<gateway_node>/cdp-proxy-api/hbase/users/fakerow"
JSON:
curl -vi -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"Row":[{"key":"cm93NQo=", "Cell": [{"column":"Y2Y6ZQo=", "$":"dmFsdWU1Cg=="}]}]}'' \