Apache
/
hbase
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

HBASE-14813 REST documentation under package.html should go to the book 

(cherry picked from commit 0167ec37054263a273214bc0c1fd845fa294a1e9)
This commit is contained in:
Misty Stanley-Jones 2016-05-10 16:09:44 -07:00
parent a07892558b
commit 4b7933bd65
2 changed files with 237 additions and 1728 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1631
hbase-rest/src/main/java/org/apache/hadoop/hbase/rest/package.html
View File

File diff suppressed because it is too large Load Diff

334
src/main/asciidoc/_chapters/external_apis.adoc
View File

@ -80,139 +80,277 @@ of the <<security>> chapter.
The following examples use the placeholder server pass:[http://example.com:8000], and The following examples use the placeholder server pass:[http://example.com:8000], and
the following commands can all be run using `curl` or `wget` commands. You can request the following commands can all be run using `curl` or `wget` commands. You can request
plain text (the default), XML , or JSON output by adding no header for plain text, plain text (the default), XML , or JSON output by adding no header for plain text,
or the header "Accept: text/xml" for XML or "Accept: application/json" for JSON. or the header "Accept: text/xml" for XML, "Accept: application/json" for JSON, or
"Accept: application/x-protobuf" to for protocol buffers.
NOTE: Unless specified, use `GET` requests for queries, `PUT` or `POST` requests for NOTE: Unless specified, use `GET` requests for queries, `PUT` or `POST` requests for
creation or mutation, and `DELETE` for deletion. creation or mutation, and `DELETE` for deletion.
==== Cluster Information .Cluster-Wide Endpoints
[options="header", cols="2m,m,3d,6l"]
|===
|Endpoint
|HTTP Verb
|Description
|Example
.HBase Version |/version/cluster
---- |GET
http://example.com:8000/version/cluster |Version of HBase running on this cluster
---- |curl -vi -X GET \
-H "Accept: text/xml" \
"http://example.com:8000/version/cluster"
.Cluster Status |/status/cluster
---- |GET
http://example.com:8000/status/cluster |Cluster status
---- |curl -vi -X GET \
-H "Accept: text/xml" \
"http://example.com:8000/status/cluster"
.Table List |/
---- |GET
http://example.com:8000/ |List of all non-system tables
---- |curl -vi -X GET \
-H "Accept: text/xml" \
"http://example.com:8000/"
==== Table Information |===
.Table Schema (GET) .Namespace Endpoints
[options="header", cols="2m,m,3d,6l"]
|===
|Endpoint
|HTTP Verb
|Description
|Example
To retrieve the table schema, use a `GET` request with the `/schema` endpoint: |/namespaces
---- |GET
http://example.com:8000/<table>/schema |List all namespaces
---- |curl -vi -X GET \
-H "Accept: text/xml" \
"http://example.com:8000/namespaces/"
.Table Creation |/namespaces/_namespace_
To create a table, use a `PUT` request with the `/schema` endpoint: |GET
---- |Describe a specific namespace
http://example.com:8000/<table>/schema |curl -vi -X GET \
---- -H "Accept: text/xml" \
"http://example.com:8000/namespaces/special_ns"
.Table Schema Update |/namespaces/_namespace_
To update a table, use a `POST` request with the `/schema` endpoint: |POST
---- |Create a new namespace
http://example.com:8000/<table>/schema |curl -vi -X POST \
---- -H "Accept: text/xml" \
"example.com:8000/namespaces/special_ns"
.Table Deletion |/namespaces/_namespace_/tables
To delete a table, use a `DELETE` request with the `/schema` endpoint: |GET
---- |List all tables in a specific namespace
http://example.com:8000/<table>/schema |curl -vi -X GET \
---- -H "Accept: text/xml" \
"http://example.com:8000/namespaces/special_ns/tables"
.Table Regions |/namespaces/_namespace_
---- |PUT
http://example.com:8000/<table>/regions |Alter an existing namespace. Currently not used.
---- |curl -vi -X PUT \
-H "Accept: text/xml" \
"http://example.com:8000/namespaces/special_ns
|/namespaces/_namespace_
|DELETE
|Delete a namespace. The namespace must be empty.
|curl -vi -X DELETE \
-H "Accept: text/xml" \
"example.com:8000/namespaces/special_ns"
==== Gets |===
.GET a Single Cell Value .Table Endpoints
[options="header", cols="2m,m,3d,6l"]
|===
|Endpoint
|HTTP Verb
|Description
|Example
To get a single cell value, use a URL scheme like the following: |/_table_/schema
|GET
|Describe the schema of the specified table.
|curl -vi -X GET \
-H "Accept: text/xml" \
"http://example.com:8000/users/schema"
---- |/_table_/schema
http://example.com:8000/<table>/<row>/<column>:<qualifier>/<timestamp>/content:raw |POST
---- |Create a new table, or replace an existing table's schema
|curl -vi -X POST \
-H "Accept: text/xml" \
-H "Content-Type: text/xml" \
-d '&lt;?xml version="1.0" encoding="UTF-8"?>&lt;TableSchema name="users">&lt;ColumnSchema name="cf" />&lt;/TableSchema>' \
"http://example.com:8000/users/schema"
The column qualifier and timestamp are optional. Without them, the whole row will |/_table_/schema
be returned, or the newest version will be returned. |PUT
|Update an existing table with the provided schema fragment
|curl -vi -X PUT \
-H "Accept: text/xml" \
-H "Content-Type: text/xml" \
-d '&lt;?xml version="1.0" encoding="UTF-8"?>&lt;TableSchema name="users">&lt;ColumnSchema name="cf" KEEP_DELETED_CELLS="true" />&lt;/TableSchema>' \
"http://example.com:8000/users/schema"
.Multiple Single Values (Multi-Get) |/_table_/schema
|DELETE
|Delete the table. You must use the `/_table_/schema` endpoint, not just `/_table_/`.
|curl -vi -X DELETE \
-H "Accept: text/xml" \
"http://example.com:8000/users/schema"
To get multiple single values, specify multiple column:qualifier tuples and/or a start-timestamp |/_table_/regions
and end-timestamp. You can also limit the number of versions. |GET
|List the table regions
|curl -vi -X GET \
-H "Accept: text/xml" \
"http://example.com:8000/users/regions
|===
---- .Endpoints for `Get` Operations
http://example.com:8000/<table>/<row>/<column>:<qualifier>?v=<num-versions> [options="header", cols="2m,m,3d,6l"]
---- |===
|Endpoint
|HTTP Verb
|Description
|Example
.Globbing Rows |/_table_/_row_/_column:qualifier_/_timestamp_
To scan a series of rows, you can use a `*` glob |GET
character on the <row> value to glob together multiple rows. |Get the value of a single row. Values are Base-64 encoded.
|curl -vi -X GET \
-H "Accept: text/xml" \
"http://example.com:8000/users/row1"
---- curl -vi -X GET \
http://example.com:8000/urls/https|ad.doubleclick.net|* -H "Accept: text/xml" \
---- "http://example.com:8000/users/row1/cf:a/1458586888395"
==== Puts |/_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" \
"http://example.com:8000/users/row1/cf:a"
For Puts, `PUT` and `POST` are equivalent. curl -vi -X GET \
-H "Accept: text/xml" \
"http://example.com:8000/users/row1/cf:a/"
.Put a Single Value |/_table_/_row_/_column:qualifier_/?v=_number_of_versions_
The column qualifier and the timestamp are optional. |GET
|Multi-Get a specified number of versions of a given cell. Values are Base-64 encoded.
|curl -vi -X GET \
-H "Accept: text/xml" \
"http://example.com:8000/users/row1/cf:a?v=2"
---- |===
http://example.com:8000/put/<table>/<row>/<column>:<qualifier>/<timestamp>
http://example.com:8000/test/testrow/test:testcolumn
----
.Put Multiple Values .Endpoints for `Scan` Operations
To put multiple values, use a false row key. Row, column, and timestamp values in [options="header", cols="2m,m,3d,6l"]
the supplied cells override the specifications on the path, allowing you to post |===
multiple values to a table in batch. The HTTP response code indicates the status of |Endpoint
the put. Set the `Content-Type` to `text/xml` for XML encoding or to `application/x-protobuf` |HTTP Verb
for protobufs encoding. Supply the commit data in the `PUT` or `POST` body, using |Description
the <<xml_schema>> and <<protobufs_schema>> as guidelines. |Example
==== Scans |/_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:8000/users/scanner/145869072824375522207`.
|curl -vi -X PUT \
-H "Accept: text/xml" \
-H "Content-Type: text/xml" \
-d '<Scanner batch="1"/>' \
"http://example.com:8000/users/scanner/"
`PUT` and `POST` are equivalent for scans. |/_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 <codeph>u123</codeph> and use a batch size
of 100, the filter file would look like this:
.Scanner Creation +++
To create a scanner, use the `/scanner` endpoint. The HTTP response code indicates <pre>
success (201) or failure (anything else), and on successful scanner creation, the &lt;Scanner batch="100"&gt;
URI is returned which should be used to address the scanner. &lt;filter&gt;
{
"type": "PrefixFilter",
"value": "u123"
}
&lt;/filter&gt;
&lt;/Scanner&gt;
</pre>
+++
---- Pass the file to the `-d` argument of the `curl` request.
http://example.com:8000/<table>/scanner |curl -vi -X PUT \
---- -H "Accept: text/xml" \
-H "Content-Type:text/xml" \
-d @filter.txt \
"http://example.com:8000/users/scanner/"
.Scanner Get Next |/_table_/scanner/_scanner-id_
To get the next batch of cells found by the scanner, use the `/scanner/<scanner-id>' |GET
endpoint, using the URI returned by the scanner creation endpoint. If the scanner |Get the next batch from the scanner. Cell values are byte-encoded. If the scanner
is exhausted, HTTP status `204` is returned. has been exhausted, HTTP status `204` is returned.
---- |curl -vi -X GET \
http://example.com:8000/<table>/scanner/<scanner-id> -H "Accept: text/xml" \
---- "http://example.com:8000/users/scanner/145869072824375522207"
.Scanner Deletion |_table_/scanner/_scanner-id_
To delete resources associated with a scanner, send a HTTP `DELETE` request to the |DELETE
`/scanner/<scanner-id>` endpoint. |Deletes the scanner and frees the resources it used.
---- |curl -vi -X DELETE \
http://example.com:8000/<table>/scanner/<scanner-id> -H "Accept: text/xml" \
---- "http://example.com:8000/users/scanner/145869072824375522207"
|===
.Endpoints for `Put` Operations
[options="header", cols="2m,m,3d,6l"]
|===
|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, use the `base64` command-line utility. To decode the
string, use `base64 -d`. The payload is in the `--data` argument, and 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 syntax like `-d @filename.txt`.
|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>' \
"http://example.com:8000/users/fakerow"
curl -vi -X PUT \
-H "Accept: text/json" \
-H "Content-Type: text/json" \
-d '{"Row":[{"key":"cm93NQo=", "Cell": [{"column":"Y2Y6ZQo=", "$":"dmFsdWU1Cg=="}]}]}'' \
"example.com:8000/users/fakerow"
|===
[[xml_schema]] [[xml_schema]]
=== REST XML Schema === REST XML Schema
@ -349,7 +487,7 @@ http://example.com:8000/<table>/scanner/<scanner-id>
<complexType name="Node"> <complexType name="Node">
<sequence> <sequence>
<element name="region" type="tns:Region" <element name="region" type="tns:Region"
maxOccurs="unbounded" minOccurs="0"> maxOccurs="unbounded" minOccurs="0">
</element> </element>
</sequence> </sequence>
<attribute name="name" type="string"></attribute> <attribute name="name" type="string"></attribute>
@ -552,7 +690,7 @@ public class HBaseExample {
//*drop if table is already exist.* //*drop if table is already exist.*
if(dbo.isTableExist("user")){ if(dbo.isTableExist("user")){
dbo.deleteTable("user"); dbo.deleteTable("user");
} }
//*create table* //*create table*