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 / Retrieve a list of all the tables in HBase. Returns: XML entity body that contains a list of the tables like so:
restest_table1
restest_table2
POST / Create a table. Headers: Content-type: text/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:
restesta:NONENONE32147483647b:NONENONE32147483647
PUT /[table_name] Update the table schema. Headers: Content-type: text/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, stop_row: Only return the list of regions that contain the range start_row...stop_row Returns: XML entity body that describes the regions:
0101
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:
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: text/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. not supported yet. Parameters: column: specify one or more column parameters (&-separated) to get the content of specific cells. If omitted, the result will contain all columns in the row. 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: text/xml: The client is sending one or more columns of data in an XML entity. The column value must be base64 encoded. Multipart/related: The client is sending multiple columns of data encoded with boundaries. Not supported yet. Parameters: column: specify one or more column parameters (&-separated) to get the content of specific cells. If omitted, the result will contain all columns in the row. 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. Parameters: column: specify one or more column parameters (&-separated) to get the content of specific cells. If omitted, the result will contain all columns in the row. Returns: HTTP 202 (Accepted) if the column(s) were deleted. sishen comment: Delete based on timestamp currently not supported yet but we need implement it 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. Parameters: column: specify one or more column parameters (&-separated) to get the content of specific cells. If omitted, the result will contain all columns in the row. start_row, stop_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&stop_row=last_key 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] Return the current item in the scanner and advance to the next one. Think of it as a queue dequeue operation. Headers: Accept: text/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. Not supported yet. Parameters: limit: return N numbers of items 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. [email protected]:~/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
tablessubscription2NONEfalsetrue
^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. [email protected]:~/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. [email protected]:~/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. [email protected]:~/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
a:YQ==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: a:YQ==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 y1196293620892a:YQ==