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

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 application/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.
If you are using a Data Hub cluster, you must provide the basic authentication parameters in your REST query string to access the REST server end-point. For example, curl -vi -X GET \

-H "Accept: text/xml" -u "<USER>:<MY_WORKLOAD_PASSWORD>" \

For more details about the curl command, see the documentation for the curl version that ships with your operating system.

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.

Endpoint HTTP Verb Description Example

/version/cluster

GET

Version of HBase running on this cluster

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

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=="}]}]}'' \`