Hbase/HbaseRest - Hadoop Wiki

This page describes the hbase REST api. It starts with the specification. Towards the end are examples using curl as a client and a description on how to start an instance of the REST server outside of the master web UI.

System Information

GET /

Retrieve a list of all the tables in HBase.

Returns:
- XML entity body that contains a list of the tables like so:

<?xml version="1.0" encoding="UTF-8"?>
<tables>
 <table>
restest_table1
 </table>
 <table>
restest_table2
 </table>
</tables>

POST /

Create a table. Headers:
- Content-type:
  - application/xml: The client is sending the table metadata in an XML entity.
Returns:
- HTTP 200 (OK) if the table could successfully be created.

GET /[table_name]

Retrieve metadata about the table. This includes column family descriptors.

Returns:
- XML entity body that contains all the metadata about the table:

<?xml version="1.0" encoding="UTF-8"?>
<table>
 <name>
restest
 </name>
 <columnfamilies>
  <columnfamily>
   <name>
a:
   </name>
   <compression>
NONE
   </compression>
   <bloomfilter>
NONE
   </bloomfilter>
   <max-versions>
3
   </max-versions>
   <maximum-cell-size>
2147483647
   </maximum-cell-size>
  </columnfamily>
  <columnfamily>
   <name>
b:
   </name>
   <compression>
NONE
   </compression>
   <bloomfilter>
NONE
   </bloomfilter>
   <max-versions>
3
   </max-versions>
   <maximum-cell-size>
2147483647
   </maximum-cell-size>
  </columnfamily>
 </columnfamilies>
</table>

PUT /[table_name]

Update the table schema.
- Headers:
  - Content-type:
    - application/xml: The client is sending the table metadata in an XML entity.
  Returns:
  - HTTP 200 (OK) if the table could successfully be updated.

DELETE /[table_name]

Delete this table. Returns:
- HTTP 202 (Accepted) if the table could successfully be deleted.

POST /[table_name]/disable

Disable this table Returns:
- HTTP 202 (Accepted) if the table could successfully be disabled.

POST /[table_name]/enable

Enable this table Returns:
- HTTP 202 (Accepted) if the table could successfully be enabled.

GET /[table_name]/regions

Retrieve a list of the regions for this table so that you can efficiently split up the work (a la MapReduce).

Options:
- start_row, end_row: Only return the list of regions that contain the range start_row...end_row
Returns:
- XML entity body that describes the regions:

<regions>
  <region></region>
  <region>0101</region>
</regions>

Row Interaction

GET /[table_name]/row/[row_key]/timestamps

Retrieve a list of all the timestamps available for this row key.

Returns:
- XML entity body that describes the list of available timestamps:

<timestamps>
  <timestamp value="20071115T000000" uri="/first_table/row/0001/198123908129038419083" />
  <timestamp value="20071115T000800" uri="/first_table/row/0001/108293471089237018937" />
  <timestamp value="20071115T001200" uri="/first_table/row/0001/019823701983981731089" />
</timestamps>

St.Ack comment: Currently not supported in native hbase client but we should add it

GET /[table_name]/row/[row_key]/

GET /[table_name]/row/[row_key]/[timestamp]

Retrieve data from a row, constrained by an optional timestamp value.

Headers:
- Accept:
  - application/xml: The client is expecting an XML entity body that contains the
    - columns and data together.
    Multipart/related: The client is expecting raw binary data, but organized into a
    - multipart response. The client must be prepared to parse the column values out of the data.
Options:
- columns: A semicolon-delimited list of column names. If omitted, the result will contain all columns in the row.

St.Ack comment 11/17/2007: Only one column allowed in hbase currently.

POST/PUT /[table_name]/row/[row_key]/

POST/PUT /[table_name]/row/[row_key]/[timestamp]

Set the value of one or more columns for a given row key with an optional timestamp.

Headers:
- Content-type:
  - application/xml: The client is sending one or more columns of data in an XML entity.
    
    Multipart/related: The client is sending multiple columns of data encoded with boundaries.
Options:
- columns: A semicolon-delimited list of column names. This attribute is ignored when the Content-type is application/xml.
Returns:
- HTTP 200 (OK) if the column(s) could successfully be saved. HTTP 415 (Unsupported Media Type) if the query string column options do not match the Content-type header, or if the binary data of either octet-stream or Multipart/related is unreadable.

DELETE /[table_name]/row/[row_key]/

DELETE /[table_name]/row/[row_key]/[timestamp]

Delete the specified columns from the row. If there are no columns specified, then it will delete ALL columns. Optionally, specify a timestamp.

Options:
- columns: A semicolon-delimited list of column names. If omitted, the result will delete all columns in the row.
Returns:
- HTTP 202 (Accepted) if the column(s) were deleted.

Scanning

POST/PUT /[table_name]/scanner

Request that a scanner be created with the specified options. Returns a scanner ID that can be used to iterate over the results of the scanner.

Options:
- columns: A semicolon-delimited list of column names. If omitted, each result will contain all columns in the row.
  
  start_row, end_row: Starting and ending keys that enclose the region that should be scanned.
  
  timestamp: Timestamp at which to start the scanner.
Returns:
- HTTP 201 (Created) with a Location header that references the scanner URI. Example: /first_table/scanner?timestamp=1234348890231890&column=colfam1:name&start_row=first_key&end_row=last_key

St.Ack comment 11/18/2007: I added timestamp parameter. Should start_row, end_row, OR timestamp be on the URL path to sync. with how they are specified GET'ing, etc?

POST /[table_name]/scanner/[scanner_id]

Return the current item in the scanner and advance to the next one. Think of it as a queue dequeue operation.

Headers:
- Accept:
  - application/xml: The client is expecting an XML entity body that contains the
    - columns and data together.
    Multipart/related: The client is expecting raw binary data, but organized into a
    - multipart response. The client must be prepared to parse the column values out of the data.
Returns:
- HTTP 200 (OK) and an entity that describes the current row in the scanner. The entity value of this request depends on the Accept header. See the documentation for getting an individual row for data format.
  
  If the scanner is used up, HTTP 404 (Not Found).

DELETE /[table_name]/scanner/[scanner_id]

Close a scanner. You must call this when you are done using a scanner to deallocate it.

Returns:
- HTTP 202 (Accepted) if it can be closed. HTTP 404 (Not Found) if the scanner id is invalid. HTTP 410 (Gone) if the scanner is already closed or the lease time has expired.

Multiple Columns in Query String In any case where a request can take multiple column names in the query string, the syntax should be:

GET http://server:port/first_table/row/row_key?column=fam1:name&column=fam2:address

This avoids the problems with having semicolon separators in a single query string parameter, and is easily read into an array in Java.

Starting the REST Server

By default, an instance of the REST servlet runs in the master UI; just browse to http://MASTER_HOST:MASTER_PORT/api/ (Results are returned as xml by default so you may have to look at source to see results).

If you intend to use the hbase REST API heavily, to run an instance of the REST server outside of the master, do the following:

cd $HBASE_HOME
bin/hbase rest start

Pass --help to see REST server usage.

Request Spec

This is a the spec for the Hbase-REST API done under the aegis of HADOOP-2068. It was committed 11/30/2007.

Examples using curl

Here is a POST of create table.

sishen@sishen-mac:~/Work/Personal/java/apache/hbase-trunk$curl -v -X POST -T - http://localhost:60050/api/
* About to connect() to localhost port 60050 (#0)
*   Trying ::1... connected
* Connected to localhost (::1) port 60050 (#0)
> POST /api/ HTTP/1.1
> User-Agent: curl/7.16.3 (powerpc-apple-darwin9.0) libcurl/7.16.3 OpenSSL/0.9.7l zlib/1.2.3
> Host: localhost:60050
> Accept: */*
> Transfer-Encoding: chunked
> Expect: 100-continue
> 
< HTTP/1.1 100 Continue
<?xml version="1.0" encoding="UTF-8"?>
<table>
  <name>tables</name>
  <columnfamilies>
    <columnfamily>
      <name>subscription</name>
      <max-versions>2</max-versions>
      <compression>NONE</compression>
      <in-memory>false</in-memory>
      <block-cache>true</block-cache>
    </columnfamily>
  </columnfamilies>
</table>
^D
< HTTP/1.1 200 OK
< Date: Wed, 13 Aug 2008 18:59:38 GMT
< Server: Jetty/5.1.4 (Mac OS X/10.5.4 i386 java/1.5.0_13
< Content-Length: 0
< 
* Connection #0 to host localhost left intact
* Closing connection #0

Here is a POST of disable table.

sishen@sishen-mac:~/Work/Personal/java/apache/hbase-trunk$curl -v -X POST http://localhost:60050/api/tables/disable
* About to connect() to localhost port 60050 (#0)
*   Trying ::1... connected
* Connected to localhost (::1) port 60050 (#0)
> POST /api/tables/disable HTTP/1.1
> User-Agent: curl/7.16.3 (powerpc-apple-darwin9.0) libcurl/7.16.3 OpenSSL/0.9.7l zlib/1.2.3
> Host: localhost:60050
> Accept: */*
> 
< HTTP/1.1 202 Accepted
< Date: Wed, 13 Aug 2008 18:55:03 GMT
< Server: Jetty/5.1.4 (Mac OS X/10.5.4 i386 java/1.5.0_13
< Content-Length: 0
< 
* Connection #0 to host localhost left intact
* Closing connection #0

Here is a POST of enable table.

sishen@sishen-mac:~/Work/Personal/java/apache/hbase-trunk$curl -v -X POST http://localhost:60050/api/tables/enable
* About to connect() to localhost port 60050 (#0)
*   Trying ::1... connected
* Connected to localhost (::1) port 60050 (#0)
> POST /api/tables/enable HTTP/1.1
> User-Agent: curl/7.16.3 (powerpc-apple-darwin9.0) libcurl/7.16.3 OpenSSL/0.9.7l zlib/1.2.3
> Host: localhost:60050
> Accept: */*
> 
< HTTP/1.1 202 Accepted
< Date: Wed, 13 Aug 2008 18:56:20 GMT
< Server: Jetty/5.1.4 (Mac OS X/10.5.4 i386 java/1.5.0_13
< Content-Length: 0
< 
* Connection #0 to host localhost left intact
* Closing connection #0

Here is a DELETE of a table.

sishen@sishen-mac:~/Work/Personal/java/apache/hbase-trunk$curl -v -X DELETE http://localhost:60050/api/tables
* About to connect() to localhost port 60050 (#0)
*   Trying ::1... connected
* Connected to localhost (::1) port 60050 (#0)
> DELETE /api/tables HTTP/1.1
> User-Agent: curl/7.16.3 (powerpc-apple-darwin9.0) libcurl/7.16.3 OpenSSL/0.9.7l zlib/1.2.3
> Host: localhost:60050
> Accept: */*
> 
< HTTP/1.1 202 Accepted
< Date: Wed, 13 Aug 2008 18:57:41 GMT
< Server: Jetty/5.1.4 (Mac OS X/10.5.4 i386 java/1.5.0_13
< Content-Length: 0
< 
* Connection #0 to host localhost left intact
* Closing connection #0

Here is a GET of a row. Notice how values are Base64'd.

durruti:~/Documents/checkouts/hadoop-trunk/src/contrib/hbase stack$ curl -v  http://XX.XX.XX.151:60010/api/restest/row/y           
* About to connect() to XX.XX.XX.151 port 60010
*   Trying XX.XX.XX.151... * connected
* Connected to XX.XX.XX.151 (208.84.6.151) port 60010
> GET /api/restest/row/y HTTP/1.1
User-Agent: curl/7.13.1 (powerpc-apple-darwin8.0) libcurl/7.13.1 OpenSSL/0.9.7l zlib/1.2.3
Host: XX.XX.XX.151:60010
Pragma: no-cache
Accept: */*

< HTTP/1.1 200 OK
< Date: Thu, 29 Nov 2007 00:24:39 GMT
< Server: Jetty/5.1.4 (Mac OS X/10.4.11 i386 java/1.5.0_07
< Content-Type: text/xml;charset=UTF-8
< Transfer-Encoding: chunked
<?xml version="1.0" encoding="UTF-8"?>
<row>
 <column>
  <name>
a:  
  </name>
  <value>
YQ==
  </value>
 </column>

Here is an example PUT to column 'a:' of row 'y':

durruti:~/Documents/checkouts/hadoop-trunk/src/contrib/hbase stack$ curl -v -T /tmp/y.row http://XX.XX.XX.151:60010/api/restest/row/y?column=a: 
* About to connect() to XX.XX.XX.151 port 60010
*   Trying XX.XX.XX.151... * connected
* Connected to XX.XX.XX.151 (208.84.6.151) port 60010
> PUT /api/restest/row/y?column=a: HTTP/1.1
User-Agent: curl/7.13.1 (powerpc-apple-darwin8.0) libcurl/7.13.1 OpenSSL/0.9.7l zlib/1.2.3
Host: XX.XX.XX.151:60010
Pragma: no-cache
Accept: */*
Content-Length: 100
Expect: 100-continue

< HTTP/1.1 100 Continue
< HTTP/1.1 200 OK
< Date: Thu, 29 Nov 2007 00:26:36 GMT
< Server: Jetty/5.1.4 (Mac OS X/10.4.11 i386 java/1.5.0_07
< Content-Length: 0

The file /tmp/y.row has these contents:

<?xml version="1.0" encoding="UTF-8"?> <column>  <name>a:  </name>  <value>YQ==  </value> </column>

Here is example that gets a scanner and then does a next to obtain first row value (The '-T /tmp/y.row' is just to fake curl into doing a POST):

durruti:~/Documents/checkouts/hadoop-trunk/src/contrib/hbase stack$ curl -v -T /tmp/y.row http://XX.XX.XX.151:60010/api/restest/scanner?column=a:
* About to connect() to XX.XX.XX.151 port 60010
*   Trying XX.XX.XX.151... * connected
* Connected to XX.XX.XX.151 (XX.XX.XX.151) port 60010
> PUT /api/restest/scanner?column=a: HTTP/1.1
User-Agent: curl/7.13.1 (powerpc-apple-darwin8.0) libcurl/7.13.1 OpenSSL/0.9.7l zlib/1.2.3
Host: XX.XX.XX.151:60010
Pragma: no-cache
Accept: */*
Content-Length: 100
Expect: 100-continue

< HTTP/1.1 100 Continue
< HTTP/1.1 201 Created
< Date: Thu, 29 Nov 2007 00:20:50 GMT
< Server: Jetty/5.1.4 (Mac OS X/10.4.11 i386 java/1.5.0_07
< Location: /api/restest/scanner/e5e2ce25
< Content-Length: 0
* Connection #0 to host XX.XX.XX.151 left intact
* Closing connection #0
durruti:~/Documents/checkouts/hadoop-trunk/src/contrib/hbase stack$ curl -v -T /tmp/y.row http://208.84.6.151:60010/api/restest/scanner/e5e2ce25
* About to connect() to XX.XX.XX.151 port 60010
*   Trying XX.XX.XX.151... * connected
* Connected to XX.XX.XX.151 (208.84.6.151) port 60010
> PUT /api/restest/scanner/e5e2ce25 HTTP/1.1
User-Agent: curl/7.13.1 (powerpc-apple-darwin8.0) libcurl/7.13.1 OpenSSL/0.9.7l zlib/1.2.3
Host: XX.XX.XX.151:60010
Pragma: no-cache
Accept: */*
Content-Length: 100
Expect: 100-continue

< HTTP/1.1 100 Continue
< HTTP/1.1 200 OK
< Date: Thu, 29 Nov 2007 00:20:58 GMT
< Server: Jetty/5.1.4 (Mac OS X/10.4.11 i386 java/1.5.0_07
< Content-Type: text/xml;charset=UTF-8
< Transfer-Encoding: chunked
<?xml version="1.0" encoding="UTF-8"?>
<row>
 <name>
y
 </name>
 <timestamp>
1196293620892
 </timestamp>
 <column>
  <name>
a:
  </name>
  <value>
YQ==
  </value>
 </column>