DEPRECATED

This page describes the deprecated o.a.h.h.rest REST server. Its been replaced by stargate. See the contrib/stargate package in hbase. Its documentation can be found here: stargate description

Old Documentation

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 -- it won't work with a browser -- on how to start an instance of the REST server outside of the master web UI.

NOTE: REST was refactored in hbase 0.20.0 (not out as of this writing). While the API was preserved, the implementation now supports XML or JSON serialization. See HBASE-1064 for detail -- stack on 01/21/2009

System Information

GET /

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

POST /

GET /[table_name]

<?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]

DELETE /[table_name]

POST /[table_name]/disable

POST /[table_name]/enable

GET /[table_name]/regions

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

Row Interaction

GET /[table_name]/row/[row_key]/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]

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

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

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

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

sishen comment: Delete based on timestamp currently not supported yet but we need implement it

Scanning

POST/PUT /[table_name]/scanner

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

POST /[table_name]/scanner/[scanner_id]

DELETE /[table_name]/scanner/[scanner_id]

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>

Hbase/HbaseRest (last edited 2010-06-15 12:54:16 by VitalyKuznetsov)