From df7632ea2e2c229b07719512592a87331a8db5cf Mon Sep 17 00:00:00 2001 From: Wellington Chevreuil Date: Wed, 4 Sep 2019 18:24:09 +0100 Subject: [PATCH] added supported content-type/accept for each end point --- .../asciidoc/_chapters/external_apis.adoc | 185 ++++++++++++------ 1 file changed, 122 insertions(+), 63 deletions(-) diff --git a/src/main/asciidoc/_chapters/external_apis.adoc b/src/main/asciidoc/_chapters/external_apis.adoc index b7aebb4655..48a9a5547e 100644 --- a/src/main/asciidoc/_chapters/external_apis.adoc +++ b/src/main/asciidoc/_chapters/external_apis.adoc @@ -87,67 +87,95 @@ NOTE: Unless specified, use `GET` requests for queries, `PUT` or `POST` requests creation or mutation, and `DELETE` for deletion. .Cluster-Wide Endpoints -[options="header", cols="2m,m,3d,6l"] +[options="header", cols="2m,2m,2m,2m,3d,6l"] |=== |Endpoint |HTTP Verb +|Content types +|Accept types |Description |Example -|/version/cluster +|/ |GET -|Version of HBase running on this cluster +|Any +|text/plain, text/xml, application/json, application/x-protobuff, application/protobuff +|List of all non-system tables. |curl -vi -X GET \ -H "Accept: text/xml" \ - "http://example.com:8000/version/cluster" + "http://example.com:8000/" -|/status/cluster +|/version |GET -|Cluster status +|Any +|text/plain, text/xml, application/json, application/x-protobuff, application/protobuff +|Shows HBase REST API version information. |curl -vi -X GET \ -H "Accept: text/xml" \ - "http://example.com:8000/status/cluster" + "http://example.com:8000/version" -|/ +|/version/cluster |GET -|List of all non-system tables +|Any +|text/plain, text/xml, application/json, application/x-protobuff, application/protobuff +|Version of HBase running on this cluster. |curl -vi -X GET \ -H "Accept: text/xml" \ - "http://example.com:8000/" + "http://example.com:8000/version/cluster" + +|/status/cluster +|GET +|Any +|text/plain, text/xml, application/json, application/x-protobuff, application/protobuff +|Shows current cluster overall status. +|curl -vi -X GET \ + -H "Accept: text/xml" \ + "http://example.com:8000/status/cluster" |=== .Namespace Endpoints -[options="header", cols="2m,m,3d,6l"] +[options="header", cols="2m,2m,2m,2m,3d,6l"] |=== |Endpoint |HTTP Verb +|Content types +|Accept types |Description |Example |/namespaces |GET -|List all namespaces +|Any +|text/plain, text/xml, application/json, application/x-protobuff, application/protobuff +|List all namespaces. |curl -vi -X GET \ -H "Accept: text/xml" \ "http://example.com:8000/namespaces/" |/namespaces/_namespace_ |GET -|Describe a specific namespace +|Any +|text/plain, text/xml, application/json, application/x-protobuff, application/protobuff +|Describe a specific namespace. |curl -vi -X GET \ -H "Accept: text/xml" \ "http://example.com:8000/namespaces/special_ns" |/namespaces/_namespace_ |POST -|Create a new namespace +|text/xml, application/json, application/x-protobuff, application/protobuff +|Not applicable +|Create a new namespace. Optionally, allows for extra properties to be specified in the payload +(which would be same one as shown on PUT example). |curl -vi -X POST \ -H "Accept: text/xml" \ - "example.com:8000/namespaces/special_ns" + "http://example.com:8000/namespaces/special_ns" |/namespaces/_namespace_/tables |GET +|Any +|text/plain, text/xml, application/json, application/x-protobuff, application/protobuff |List all tables in a specific namespace |curl -vi -X GET \ -H "Accept: text/xml" \ @@ -155,13 +183,19 @@ creation or mutation, and `DELETE` for deletion. |/namespaces/_namespace_ |PUT -|Alter an existing namespace. Currently not used. +|text/xml, application/json, application/x-protobuff, application/protobuff +|Not applicable +|Alter an existing namespace, setting properties passed in +the request payload to the given namespace. |curl -vi -X PUT \ - -H "Accept: text/xml" \ - "http://example.com:8000/namespaces/special_ns + -H "Content-Type: application/json" \ + -d '{"properties":{"test property 1":"test property value 1"}}' \ + "http://localhost:8080/namespaces/special_ns" |/namespaces/_namespace_ |DELETE +|Any +|Not applicable |Delete a namespace. The namespace must be empty. |curl -vi -X DELETE \ -H "Accept: text/xml" \ @@ -170,23 +204,29 @@ creation or mutation, and `DELETE` for deletion. |=== .Table Endpoints -[options="header", cols="2m,m,3d,6l"] +[options="header", cols="2m,2m,2m,2m,3d,6l"] |=== |Endpoint |HTTP Verb +|Content types +|Accept types |Description |Example |/_table_/schema |GET -|Describe the schema of the specified table. +|Any +|text/plain, text/xml, application/json, application/x-protobuff, application/protobuff +|Describes the schema of the specified table. |curl -vi -X GET \ -H "Accept: text/xml" \ "http://example.com:8000/users/schema" |/_table_/schema |POST -|Update an existing table with the provided schema fragment +|text/xml, application/json, application/x-protobuff, application/protobuff +|Not applicable +|Creates a new table, or replace an existing table's schema. |curl -vi -X POST \ -H "Accept: text/xml" \ -H "Content-Type: text/xml" \ @@ -195,7 +235,9 @@ creation or mutation, and `DELETE` for deletion. |/_table_/schema |PUT -|Create a new table, or replace an existing table's schema +|text/xml, application/json, application/x-protobuff, application/protobuff +|Not applicable +|Updates an existing table with the provided schema fragment. |curl -vi -X PUT \ -H "Accept: text/xml" \ -H "Content-Type: text/xml" \ @@ -204,44 +246,56 @@ creation or mutation, and `DELETE` for deletion. |/_table_/schema |DELETE -|Delete the table. You must use the `/_table_/schema` endpoint, not just `/_table_/`. +|Any +|Not applicable +|Deletes 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" |/_table_/regions |GET -|List the table regions +|Any +|text/plain, text/xml, application/json, application/x-protobuff, application/protobuff +|Lists the table regions. |curl -vi -X GET \ -H "Accept: text/xml" \ "http://example.com:8000/users/regions |=== .Endpoints for `Get` Operations -[options="header", cols="2m,m,3d,6l"] +[options="header", cols="2m,2m,2m,2m,3d,6l"] |=== |Endpoint |HTTP Verb +|Content types +|Accept types |Description |Example |/_table_/_row_ |GET -|Get all columns of a single row. Values are Base-64 encoded. This requires the "Accept" request header with a type that can hold multiple columns (like xml, json or protobuf). +|Any +|text/plain, text/xml, application/json, application/x-protobuff, application/protobuff +|Gets all columns of a single row. Values are Base-64 encoded. |curl -vi -X GET \ -H "Accept: text/xml" \ "http://example.com:8000/users/row1" |/_table_/_row_/_column:qualifier_/_timestamp_ |GET -|Get the value of a single column. Values are Base-64 encoded. +|Any +|text/plain, text/xml, application/json, application/x-protobuff, application/protobuff, application/octet-stream +|Gets the value of a single column. For non binary mime-types, values are Base-64 encoded. |curl -vi -X GET \ -H "Accept: text/xml" \ "http://example.com:8000/users/row1/cf:a/1458586888395" |/_table_/_row_/_column:qualifier_ |GET -|Get the value of a single column. Values are Base-64 encoded. +|Any +|text/plain, text/xml, application/json, application/x-protobuff, application/protobuff, application/octet-stream +|Gets the value of a single column. For non binary accept types, values are Base-64 encoded. |curl -vi -X GET \ -H "Accept: text/xml" \ "http://example.com:8000/users/row1/cf:a" @@ -252,7 +306,9 @@ curl -vi -X GET \ |/_table_/_row_/_column:qualifier_/?v=_number_of_versions_ |GET -|Multi-Get a specified number of versions of a given cell. Values are Base-64 encoded. +|Any +|text/plain, text/xml, application/json, application/x-protobuff, application/protobuff, application/octet-stream +|Multi-Gets a specified number of versions of a given cell. For non binary mime-types, values are Base-64 encoded. |curl -vi -X GET \ -H "Accept: text/xml" \ "http://example.com:8000/users/row1/cf:a?v=2" @@ -260,48 +316,42 @@ curl -vi -X GET \ |=== .Endpoints for `Scan` Operations -[options="header", cols="2m,m,3d,6l"] +[options="header", cols="2m,2m,2m,2m,3d,6l"] |=== |Endpoint |HTTP Verb +|Content types +|Accept types |Description |Example |/_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 +|text/xml, application/json, application/x-protobuff, application/protobuff +|Not applicable +|Gets a Scanner object. Required by all other Scan operations. +The scan batch size defining number of rows to be returned by the scan must be specified +in the payload (see examples). + +Additional filters and properties can be defined to the scan. For example, to return only rows for +which keys start with "u123" and use a batch size of 100, payload would look like this: + +{"type": "PrefixFilter","value": "u123"} + +The scanner endpoint URL is returned in the HTTP response header `Location` parameter. +Remaining examples in this table assume that the scanner endpoint is `\http://example.com:8000/users/scanner/145869072824375522207`. -|curl -vi -X PUT \ + +| +1)A simple scan with bacth set to 1:\ +curl -vi -X PUT \ -H "Accept: text/xml" \ -H "Content-Type: text/xml" \ -d '' \ "http://example.com:8000/users/scanner/" -|/_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 u123 and use a batch size -of 100, the filter file would look like this: - -[source,xml] ----- - - - { - "type": "PrefixFilter", - "value": "u123" - } - - ----- - -Pass the file to the `-d` argument of the `curl` request. -|curl -vi -X PUT \ +2) A scan defining filters in _filter.txt_ file:\ +curl -vi -X PUT \ -H "Accept: text/xml" \ -H "Content-Type:text/xml" \ -d @filter.txt \ @@ -309,7 +359,9 @@ Pass the file to the `-d` argument of the `curl` request. |/_table_/scanner/_scanner-id_ |GET -|Get the next batch from the scanner. Cell values are byte-encoded. If the scanner +|Any +|text/xml, application/json, application/x-protobuff, application/protobuff +|Gets the next batch from the scanner. Cell values are byte-encoded. If the scanner has been exhausted, HTTP status `204` is returned. |curl -vi -X GET \ -H "Accept: text/xml" \ @@ -317,6 +369,8 @@ has been exhausted, HTTP status `204` is returned. |_table_/scanner/_scanner-id_ |DELETE +|Any +|Not applicable |Deletes the scanner and frees the resources it used. |curl -vi -X DELETE \ -H "Accept: text/xml" \ @@ -325,20 +379,25 @@ has been exhausted, HTTP status `204` is returned. |=== .Endpoints for `Put` Operations -[options="header", cols="2m,m,3d,6l"] +[options="header", cols="2m,2m,2m,2m,3d,6l"] |=== |Endpoint |HTTP Verb +|Content types +|Accept types |Description |Example |/_table_/_row_key_ |PUT -|Write a row to a table. The row, column qualifier, and value must each be Base-64 +|text/xml, application/json, application/x-protobuff, application/protobuff, application/octet-steam +|Any +|Writes 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 `` -element. You can also save the data to be inserted to a file and pass it to the `-d` +string, use `base64 -d`. The payload, in this _curl_ example, is specified with the `-d` argument, +and the `/users/fakerow` value is a placeholder. +Insert multiple rows by adding them to the `` element. +With _curl_, 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" \ -- 2.17.2 (Apple Git-113)