This is an automated email from the ASF dual-hosted git repository.
busbey pushed a commit to branch branch-2
in repository https://gitbox.apache.org/repos/asf/hbase.git
The following commit(s) were added to refs/heads/branch-2 by this push:
new 25f9070 HBASE-7129 Rest Documentation for check-and operations.
25f9070 is described below
commit 25f9070bc56eac659ed7e125db7691c177e7e33e
Author: Dequan Chen <[email protected]>
AuthorDate: Fri Jun 21 16:28:41 2019 -0700
HBASE-7129 Rest Documentation for check-and operations.
Signed-off-by: Sakthi <[email protected]>
Signed-off-by: Sean Busbey <[email protected]>
(cherry picked from commit 4e46093a9a505d3bff83fb63092dbf4860d96832)
---
src/main/asciidoc/_chapters/external_apis.adoc | 122 +++++++++++++++++++++++++
1 file changed, 122 insertions(+)
diff --git a/src/main/asciidoc/_chapters/external_apis.adoc
b/src/main/asciidoc/_chapters/external_apis.adoc
index 8f65c4e..b7aebb4 100644
--- a/src/main/asciidoc/_chapters/external_apis.adoc
+++ b/src/main/asciidoc/_chapters/external_apis.adoc
@@ -353,6 +353,128 @@ curl -vi -X PUT \
"example.com:8000/users/fakerow"
|===
+
+.Endpoints for `Check-And-Put` Operations
+[options="header", cols="2m,m,3d,6l"]
+|===
+|Endpoint
+|HTTP Verb
+|Description
+|Example
+
+|/_table_/_row_key_/?check=put
+|PUT
+|Conditional Put - Change the current version value of a cell: Compare the
current or latest version value (`current-version-value`) of a cell with the
`check-value`, and if `current-version-value` == `check-value`, write new data
(the `new-value`) into the cell as the current or latest version. 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` [...]
+|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="cm93MQ=="><Cell column="Y2ZhOmFsaWFz">T2xkR3V5</Cell><Cell
column="Y2ZhOmFsaWFz">TmV3R3V5</Cell></Row></CellSet>' \
+ "http://example.com:8000/users/row1/?check=put";
+
+curl -vi -X PUT \
+ -H "Accept: application/json" \
+ -H "Content-Type: application/json" \
+ -d
'{"Row":[{"key":"cm93MQ==","Cell":[{"column":"Y2ZhOmFsaWFz","$":"T2xkR3V5"},{"column":"Y2ZhOmFsaWFz",
"$":"TmV3R3V5"}] }]}' \
+ "http://example.com:8000/users/row1/?check=put";
+|===
+Detailed Explanation:
+
+*** In the above json-format example:
+1. `{"column":"Y2ZhOmFsaWFz", "$":"TmV3R3V5"}` at the end of `-d` option are
`the check cell name and check cell value in Base-64` respectively:
`"Y2ZhOmFsaWFz" for "cfa:alias"`, and `"TmV3R3V5" for "NewGuy"`
+2. `{"column":"Y2ZhOmFsaWFz","$":"T2xkR3V5"}` are `the new Put cell name and
cell value in Base-64` respectively: `"Y2ZhOmFsaWFz" for "cfa:alias"`, and
`"T2xkR3V5" for "OldGuy"`
+3. `"cm93MQ=="` is `the Base-64 for "row1"` for the checkAndPut `row key`
+4. `"/?check=put"` after the `"row key" in the request URL` is required for
checkAndPut WebHBase operation to work
+5. The `"row key" in the request URL` should be URL-encoded, e.g.,
`"david%20chen"` and `"row1"` are the URL-encoded formats of row keys `"david
chen"` and `"row1"`, respectively
+
+ Note: "cfa" is the column family name and "alias" are the column (qualifier)
name for the non-Base64 encoded cell name.
+
+*** Basically, the xml-format example is the same as the json-format example,
and will not be explained here in detail.
+
+.Endpoints for `Check-And-Delete` Operations
+[options="header", cols="2m,m,3d,6l"]
+|===
+|Endpoint
+|HTTP Verb
+|Description
+|Example
+
+|/_table_/_row_key_/?check=delete
+|DELETE
+|Conditional Deleting a Row: Compare the value of any version of a cell
(`any-version-value`) with the `check-value`, and if `any-version-value` ==
`check-value`, delete the row specified by the `row_key` inside the requesting
URL.The row, column qualifier, and value for checking in the payload 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. You
can also save the data to be [...]
+|curl -vi -X DELETE \
+ -H "Accept: text/xml" \
+ -H "Content-Type: text/xml" \
+ -d '<?xml version="1.0" encoding="UTF-8" standalone="yes"?><CellSet><Row
key="cm93MQ=="><Cell column="Y2ZhOmFsaWFz">TmV3R3V5</Cell></Row></CellSet>' \
+ "http://example.com:8000/users/row1/?check=delete";
+
+curl -vi -X DELETE \
+ -H "Accept: application/json" \
+ -H "Content-Type: application/json" \
+ -d
'{"Row":[{"key":"cm93MQ==","Cell":[{"column":"Y2ZhOmFsaWFz","$":"TmV3R3V5"}]}]}'
\
+ "http://example.com:8000/users/row1/?check=delete";
+
+|/_table_/_row_key_
+/_column_family_
+/?check=delete
+|DELETE
+|Conditional Deleting a Column Family of a Row: Compare the value of any
version of a cell (`any-version-value`) with the `check-value`, and if
`any-version-value` == `check-value`, delete the column family of a row
specified by the `row_key/column_family` inside the requesting URL. Anything
else is the same as those in `Conditional Deleting a Row`.
+|curl -vi -X DELETE \
+ -H "Accept: text/xml" \
+ -H "Content-Type: text/xml" \
+ -d '<?xml version="1.0" encoding="UTF-8" standalone="yes"?><CellSet><Row
key="cm93MQ=="><Cell column="Y2ZhOmFsaWFz">TmV3R3V5</Cell></Row></CellSet>' \
+ "http://example.com:8000/users/row1/cfa/?check=delete";
+
+curl -vi -X DELETE \
+ -H "Accept: application/json" \
+ -H "Content-Type: application/json" \
+ -d
'{"Row":[{"key":"cm93MQ==","Cell":[{"column":"Y2ZhOmFsaWFz","$":"TmV3R3V5"}]}]}'
\
+ "http://example.com:8000/users/row1/cfa/?check=delete";
+
+|/_table_/_row_key_
+/_column:qualifier_
+/?check=delete
+|DELETE
+|Conditional Deleting All Versions of a Column of a Row: Compare the value of
any version of a cell (`any-version-value`) with the `check-value`, and if
`any-version-value` == `check-value`, delete the column of a row specified by
the `row_key/column:qualifier` inside the requesting URL. The
`column:qualifier` in the requesting URL is the `column_family:column_name`.
Anything else is the same as those in `Conditional Deleting a Row`.
+|curl -vi -X DELETE \
+ -H "Accept: text/xml" \
+ -H "Content-Type: text/xml" \
+ -d '<?xml version="1.0" encoding="UTF-8" standalone="yes"?><CellSet><Row
key="cm93MQ=="><Cell column="Y2ZhOmFsaWFz">TmV3R3V5</Cell></Row></CellSet>' \
+ "http://example.com:8000/users/row1/cfa:alias/?check=delete";
+
+curl -vi -X DELETE \
+ -H "Accept: application/json" \
+ -H "Content-Type: application/json" \
+ -d
'{"Row":[{"key":"cm93MQ==","Cell":[{"column":"Y2ZhOmFsaWFz","$":"TmV3R3V5"}]}]}'
\
+ "http://example.com:8000/users/row1/cfa:alias/?check=delete";
+
+|/_table_/_row_key_
+/_column:qualifier_
+/_version_id_/?check=delete
+|DELETE
+|Conditional Deleting a Single Version of a Column of a Row: Compare the value
of any version of a cell (`any-version-value`) with the `check-value`, and if
`any-version-value` == `check-value`, delete the version of a column of a row
specified by the `row_key/column:qualifier/version_id` inside the requesting
URL. The `column:qualifier` in the requesting URL is the
`column_family:column_name`. The `version_id` in the requesting URL is a
number, which equals to `the timestamp of the targ [...]
+|curl -vi -X DELETE \
+ -H "Accept: text/xml" \
+ -H "Content-Type: text/xml" \
+ -d '<?xml version="1.0" encoding="UTF-8" standalone="yes"?><CellSet><Row
key="cm93MQ=="><Cell column="Y2ZhOmFsaWFz">TmV3R3V5</Cell></Row></CellSet>' \
+ "http://example.com:8000/users/row1/cfa:alias/1519423552160/?check=delete";
+
+curl -vi -X DELETE \
+ -H "Accept: application/json" \
+ -H "Content-Type: application/json" \
+ -d
'{"Row":[{"key":"cm93MQ==","Cell":[{"column":"Y2ZhOmFsaWFz","$":"TmV3R3V5"}]}]}'
\
+ "http://example.com:8000/users/row1/cfa:alias/1519423552160/?check=delete";
+|===
+Detailed Explanation:
+
+*** In the above 4 json-format examples:
+1. `{"column":"Y2ZhOmFsaWFz", "$":"TmV3R3V5"}` at the end of `-d` option are
`the check cell name and check cell value in Base-64` respectively:
`"Y2ZhOmFsaWFz" for "cfa:alias"`, and `"TmV3R3V5" for "NewGuy"`
+2. `"cm93MQ=="` is `the Base-64 for "row1"` for the checkAndDelete `row key`
+3. `"/?check=delete"` at the end of `the request URL` is required for
checkAndDelete WebHBase operation to work
+4. `"version_id"` in the `request URL` of the last json-format example should
be equivalent to the value of `"the timestamp number + 1"`
+5. The `"row key"`, `"column family"`, `"cell name" or "column family:column
name"`, and `"version_id"` in `the request URL` of a checkAndDelete WebHBase
operation should be URL-encoded, e.g., `"row1"`, `"cfa"`, `"cfa:alias"` and
`"1519423552160"` in the examples are the URL-encoded `"row key"`, `"column
family"`, `"column family:column name"`, and `"version_id"`, respectively
+
+*** Basically, the 4 xml-format examples are the same as the 4 corresponding
json-format examples, and will not be explained here in detail.
+
[[xml_schema]]
=== REST XML Schema
