From 9bba58d2171a47f8786beefc04197b6cae431fb7 Mon Sep 17 00:00:00 2001 From: Andrew Kyle Purtell Date: Sun, 26 Jul 2009 06:30:05 +0000 Subject: [PATCH] table of contents git-svn-id: https://svn.apache.org/repos/asf/hadoop/hbase/trunk@797864 13f79535-47bb-0310-9956-ffa450edef68 --- .../apache/hadoop/hbase/stargate/package.html | 182 ++++++++++++++++-- 1 file changed, 168 insertions(+), 14 deletions(-) diff --git a/src/contrib/stargate/src/java/org/apache/hadoop/hbase/stargate/package.html b/src/contrib/stargate/src/java/org/apache/hadoop/hbase/stargate/package.html index 8c4c32733a2..2383e84eb2c 100755 --- a/src/contrib/stargate/src/java/org/apache/hadoop/hbase/stargate/package.html +++ b/src/contrib/stargate/src/java/org/apache/hadoop/hbase/stargate/package.html @@ -26,7 +26,55 @@ This package provides "Stargate" -- a RESTful Web service front end for HBase.

- +

Table Of Contents

+
    +
  1. Deployment
    2. +
      +
    1. Daemon
      2. +
    2. Servlet
      3. +
    +
  2. Representational State Transfer
    3. +
  3. Resource Identifiers
    4. +
  4. Operations
    5. +
      +
    1. Query Software Version
      2. +
    2. Query Storage Cluster Version
      3. +
    3. Query Storage Cluster Status
      4. +
    4. Query Table List
      5. +
    5. Query Table Schema
      6. +
    6. Create Table Or Update Table Schema
      7. +
    7. Query Table Metadata
      8. +
    8. Delete Table
      9. +
    9. Cell Query (Single Value)
      10. +
    10. Cell or Row Query (Multiple Values)
      11. +
    11. Cell Store (Single)
      12. +
    12. Cell Store (Multiple)
      13. +
    13. Row, Column, or Cell Delete
      14. +
    14. Scanner Creation
      15. +
    15. Scanner Get Next
      16. +
    16. Scanner Deletion
      17. +
    +
  5. XML Schema
    6. +
  6. Protobufs Schema
    7. +
+ +

+ +

Deployment

+ +

+ +

+ +

Daemon

+ +

+ +

+ +

Servlet

+ +

@@ -153,10 +201,14 @@ Address with table, row, column (and optional qualifier), and optional timestamp

+

Operations

+

+

Query Software Version

+ 

 GET /version
@@ -192,6 +244,7 @@ Cache-Control: no-cache

 Content-Type: text/xml

 Content-Length: 212

 

+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

 <Version Stargate="0.0.1" OS="Linux 2.6.18-128.1.6.el5.centos.plusxen amd64"

  JVM="Sun Microsystems Inc. 1.6.0_13-11.3-b02" Jetty="6.1.14" Jersey="1.1.0-e

 a"/>

@@ -226,7 +279,54 @@ Content-Type: application/x-protobuf

 
 

 
+
 
Query Storage Cluster Version

+
+

+
+GET /version/cluster
+

+

+Returns version information regarding the HBase cluster backing the Stargate instance.
+

+Examples:
+

+

+
+% curl http://localhost:8000/version/cluster

+

+HTTP/1.1 200 OK

+Content-Length: 6

+Cache-Control: no-cache

+Content-Type: text/plain

+

+0.20.0

+

+% curl -H "Accept: text/xml" http://localhost:8000/version/cluster

+

+HTTP/1.1 200 OK

+Cache-Control: no-cache

+Content-Type: text/xml

+Content-Length: 94

+

+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

+<ClusterVersion>0.20.0</ClusterVersion>

+

+% curl -H "Accept: application/json" http://localhost:8000/version/cluster

+

+HTTP/1.1 200 OK

+Cache-Control: no-cache

+Content-Type: application/json

+Transfer-Encoding: chunked

+

+"0.20.0"

+
+

+

+
+
+
Query Storage Cluster Status

+
 

 
 GET /status/cluster
@@ -275,6 +375,7 @@ Cache-Control: no-cache

 Content-Type: text/xml

 Content-Length: 1301

 

+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

 <ClusterStatus requests="1" regions="13" averageLoad="13.0"><DeadNodes/><LiveN

 odes><Node startCode="1244960965781" requests="1" name="test:37154"><Region na

 me="dXJscyxodHRwfHd3dy5sZWdhY3kuY29tfDgwfHNpdGU9TGVnYWN5fGFhbXN6PTMwMHgyNTB8YX

@@ -319,8 +420,9 @@ TE4Nw=="}]}}}

 
 

 
-
+
 
Query Table List

+
 

 
 GET /
@@ -355,6 +457,7 @@ Cache-Control: no-cache

 Content-Type: text/xml

 Content-Length: 121

 

+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

 <TableList><table name="content"/><table name="urls"/></TableList>

 

 % curl -H "Accept: application/json" http://localhost:8000/

@@ -378,7 +481,9 @@ Content-Type: application/x-protobuf

 
 

 
+
 
Query Table Schema

+
 

 
 GET /<table>/schema
@@ -420,6 +525,7 @@ Cache-Control: no-cache

 Content-Type: text/xml

 Content-Length: 618

 

+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

 <TableSchema name="content" IS_META="false" IS_ROOT="false"><ColumnSchema nam

 e="content" BLOCKSIZE="65536" BLOOMFILTER="false" BLOCKCACHE="false" COMPRESS

 ION="GZ" LENGTH="2147483647" VERSIONS="1" TTL="-1" IN_MEMORY="false"/><Column

@@ -462,10 +568,13 @@ Content-Type: application/x-protobuf

 
 

 
+
 
Create Table Or Update Table Schema

+
 

 
 PUT /<table>/schema
+
 POST /<table>/schema
 

 

@@ -478,13 +587,15 @@ in the desired encoding.
 Set Content-Type header to text/xml if the desired encoding is XML.
 Set Content-Type header to application/json if the desired encoding
 is JSON.
-Set Content-Type header to application/x-protobuftt> if the desired
+Set Content-Type header to application/x-protobuf if the desired
 encoding is protobufs.
 If not successful, returns appropriate HTTP error status code.
 If successful, returns HTTP 200 status.
 

 
+
 
Query Table Metadata

+
 

 
 GET /<table>/regions
@@ -509,6 +620,7 @@ Cache-Control: no-cache

 Content-Type: text/xml

 Content-Length: 1555

 

+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

 <TableInfo name="content"><Region location="test:51025" endKey="M2VmMTZkNzc2Nj

 AzYmY5YjllNzc1YzljZWI2NDg2MGY=" startKey="" id="1244851999187" name="content,,

 1244851999187"/><Region location="test:51025" endKey="NjAxMjkyYTgzOWI5NWU1MDIw

@@ -574,7 +686,9 @@ Content-Type: application/x-protobuf

 
 

 
+
 
Delete Table

+
 

 
 DELETE /<table>/schema
@@ -599,7 +713,9 @@ Content-Length: 0

 
 

 
+
 
Cell Query (Single Value)

+
 

 
 GET /<table>/<row>/
@@ -615,7 +731,8 @@ If not successful, returns appropriate HTTP error status code.
 If successful, returns HTTP 200 status and cell data in the response body in
 the requested encoding. If the encoding is binary, returns row, column, and
 timestamp in X headers: X-Row, X-Column, and 
-X-Timestamp, respectively.
+X-Timestamp, respectively. Depending on the precision of the resource
+specification, some of the X-headers may be elided as redundant.
 

 Examples:
 

@@ -628,6 +745,7 @@ Cache-Control: max-age=14400

 Content-Type: text/xml

 Content-Length: 521

 

+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

 <CellSet><Row key="MDAwMTI2MTRmN2Q0M2RmNjQxODUyMzQ0NWE2Nzg3ZDY="><Cell timesta

 mp="1244880122250" column="Y29udGVudDpyYXc=">PCFET0NUWVBFIEhUTUwgUFVCTElDICItL

 y9JRVRGLy9EVEQgSFRNTCAyLjAvL0VOIj4KPGh0bWw+PGhlYWQ+Cjx0aXRsZT4zMDEgTW92ZWQgUGV

@@ -676,7 +794,9 @@ Content-Type: application/octet-stream

 
 

 
+
 
Cell or Row Query (Multiple Values)

+
 

 
 GET /<table>/<row>
@@ -689,12 +809,20 @@ GET /<table>/<row>
 Retrieves one or more cells from a full row, or one or more specified columns
 in the row, with optional filtering via timestamp, and an optional restriction
 on the maximum number of versions to return.
-Set Accept header to text/xml for XML reply.
+Set Accept header to text/xml for XML reply.
 Set Accept header to application/json for JSON reply.
 Set Accept header to application/x-protobuf for protobufs.
+Set Accept header to application/octet-stream for binary.
 If not successful, returns appropriate HTTP error status code.
 If successful, returns row results in the requested encoding. 
 

+NOTE: If binary encoding is requested, only one cell can be returned, the 
+first to match the resource specification. The row, column, and timestamp
+associated with the cell will be transmitted in X headers: X-Row,
+X-Column, and X-Timestamp, respectively. Depending on the
+precision of the resource specification, some of the X-headers may be elided
+as redundant.
+

 Suffix Globbing
 

 Multiple value queries of a row can optionally append a suffix glob on the row
@@ -720,6 +848,7 @@ Cache-Control: max-age=14400

 Content-Type: text/xml

 Transfer-Encoding: chunked

 

+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

 <CellSet><Row key="aHR0cHx3d3cudGVsZWdyYXBoLmNvLnVrfDgwfG5ld3N8d29ybGRuZXdzfG5

 vcnRoYW1lcmljYXx1c2F8NTQ5MTI4NHxBcm5vbGQtU2Nod2FyemVuZWdnZXItdW52ZWlscy1wYXBlc

 mxlc3MtY2xhc3Nyb29tcy1wbGFuLmh0bWw="><Cell timestamp="1244701257843" column="a

@@ -797,7 +926,9 @@ Content-Type: application/x-protobuf

 
 

 
-
Cell Store (Single Value)

+
+
Cell Store (Single)

+
 

 
 PUT /<table>/<row>/<column>( : <qualifier> )? ( / <timestamp> )?
@@ -814,6 +945,11 @@ Set Content-Type header to application/octet-stream for binary encoding
 When using binary encoding, optionally, set X-Timestamp header to the desired
 timestamp.
 

+PUT and POST operations are equivalent here: Specified addresses without
+existing data will create new values. Specified addresses with existing data 
+will create new versions, overwriting an existing version if all of { row,
+column:qualifer, timestamp } match that of the existing value.
+

 See "Cell Query (Single Value)" section for encoding examples.
 

 Examples:
@@ -828,7 +964,9 @@ Content-Length: 0

 
 

 
-
Cell Store (Batched)

+
+
Cell Store (Multiple)

+
 

 
 PUT /<table>/<false-row-key>
@@ -842,11 +980,19 @@ multiple values to a table in batch. If not successful, returns appropriate
 HTTP error status code. If successful, returns HTTP 200 status.
 Set Content-Type to text/xml for XML encoding.
 Set Content-Type header to application/x-protobuf for protobufs encoding.
-Supply commit data in the PUT or POST body. See "Cell or Row Query (Multiple
-Values)" for encoding examples.
+Supply commit data in the PUT or POST body. 
+

+PUT and POST operations are equivalent here: Specified addresses without
+existing data will create new values. Specified addresses with existing data 
+will create new versions, overwriting an existing version if all of { row,
+column:qualifer, timestamp } match that of the existing value.
+

+See "Cell or Row Query (Multiple Values)" for encoding examples.
 

 
+
 
Row, Column, or Cell Delete

+
 

 
 DELETE /<table>/<row>
@@ -862,16 +1008,17 @@ NOTE: DELETE /<table> will not work.
 Use DELETE /<table>/schema instead.
 

 
+
 
Scanner Creation

+
 

 
-PUT /<table>>scanner
+PUT /<table>/scanner
 
-POST /<table>>scanner
+POST /<table>/scanner
 

 

 Allocates a new table scanner.
-Use a Cache-Control header directive of "no-cache".
 If not successful, returns appropriate HTTP error status code.
 If successful, returns HTTP 201 status (created) and the URI which should be
 used to address the scanner, e.g.
@@ -895,7 +1042,9 @@ Content-Length: 0

 
 

 
-
Scanner Get Next 

+
+
Scanner Get Next

+
 

 
 GET /<table>/scanner/<scanner-id>
@@ -911,7 +1060,9 @@ Otherwise, returns HTTP 200 status and row and cell data in the response body.
 See examples from the "Cell or Row Query (Multiple Values)" section.
 

 NOTE: The binary encoding option returns only one cell regardless of the 
-batching parameter supplied during scanner creation.
+batching parameter supplied during scanner creation. The row, column, and
+timestamp associated with the cell are transmitted as X-headers: 
+X-Row, X-Column, and X-Timestamp respectively.
 

 Examples:
 

@@ -924,6 +1075,7 @@ Cache-Control: no-cache

 Content-Type: text/xml

 Content-Length: 589

 

+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

 <CellSet><Row key="MDAyMDFjMTAwNjk4ZGNkYjU5MDQxNTVkZGQ3OGRlZTk="><Cell timesta

 mp="1244701281234" column="Y29udGVudDpyYXc=">PCFET0NUWVBFIEhUTUwgUFVCTElDICItL

 y9JRVRGLy9EVEQgSFRNTCAyLjAvL0VOIj4KPGh0bWw+PGhlYWQ+Cjx0aXRsZT40MDQgTm90IEZvdW5

@@ -974,7 +1126,9 @@ Content-Type: application/octet-stream

 
 

 
+
 
Scanner Deletion

+
 

 
 DELETE /<table>/scanner/<scanner-id>