From 7e7aacf307ed8b37b2ed049e98fdab0256db9c38 Mon Sep 17 00:00:00 2001 From: Dequan Chen Date: Tue, 27 Mar 2018 11:20:33 -0500 Subject: [PATCH 1/5] Add Endpoints of Check-And-PUT and Check-And-Delete HBase Rest Documentation for JIRA - HBASE-7129 --- src/main/asciidoc/_chapters/external_apis.adoc | 100 +++++++++++++++++++++++++ 1 file changed, 100 insertions(+) diff --git a/src/main/asciidoc/_chapters/external_apis.adoc b/src/main/asciidoc/_chapters/external_apis.adoc index ffb6ee6cbf..886cc38287 100644 --- a/src/main/asciidoc/_chapters/external_apis.adoc +++ b/src/main/asciidoc/_chapters/external_apis.adoc @@ -353,6 +353,106 @@ 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 argument, with check column qualifier and value at the end or right after the new column qualifier and value of the same row key. 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 'T2xkR3V5TmV3R3V5' \ + "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" +|=== + +.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 checked to a file and pass it to the `-d` parameter with syntax like `-d @filename.txt`. +|curl -vi -X DELETE \ + -H "Accept: text/xml" \ + -H "Content-Type: text/xml" \ + -d 'TmV3R3V5' \ + "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 'TmV3R3V5' \ + "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 'TmV3R3V5' \ + "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 targeted version + 1`. 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 'TmV3R3V5' \ + "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" +|=== [[xml_schema]] === REST XML Schema -- 2.13.1.windows.2 From 8fb306f364a6dc8e216da4833231297c45e7ac7f Mon Sep 17 00:00:00 2001 From: Dequan Chen Date: Thu, 29 Mar 2018 09:00:24 -0500 Subject: [PATCH 2/5] Removed 13 whitespaces for previous HBase-9129.patch - "Add Endpoints of Check-And-PUT and Check-And-Delete HBase Rest Documentation for JIRA - HBASE-7129" --- src/main/asciidoc/_chapters/external_apis.adoc | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/src/main/asciidoc/_chapters/external_apis.adoc b/src/main/asciidoc/_chapters/external_apis.adoc index 886cc38287..dd8eaf0844 100644 --- a/src/main/asciidoc/_chapters/external_apis.adoc +++ b/src/main/asciidoc/_chapters/external_apis.adoc @@ -363,7 +363,7 @@ curl -vi -X PUT \ |Description |Example -|/_table_/_row_key_/?check=put +|/_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 argument, with check column qualifier and value at the end or right after the new column qualifier and value of the same row key. 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 \ @@ -371,7 +371,7 @@ curl -vi -X PUT \ -H "Content-Type: text/xml" \ -d 'T2xkR3V5TmV3R3V5' \ "http://example.com:8000/users/row1/?check=put" - + curl -vi -X PUT \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ @@ -387,7 +387,7 @@ curl -vi -X PUT \ |Description |Example -|/_table_/_row_key_/?check=delete +|/_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 checked to a file and pass it to the `-d` parameter with syntax like `-d @filename.txt`. |curl -vi -X DELETE \ @@ -395,16 +395,16 @@ curl -vi -X PUT \ -H "Content-Type: text/xml" \ -d 'TmV3R3V5' \ "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 +/?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 \ @@ -412,7 +412,7 @@ curl -vi -X DELETE \ -H "Content-Type: text/xml" \ -d 'TmV3R3V5' \ "http://example.com:8000/users/row1/cfa/?check=delete" - + curl -vi -X DELETE \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ @@ -421,7 +421,7 @@ curl -vi -X DELETE \ |/_table_/_row_key_ /_column:qualifier_ -/?check=delete +/?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 \ @@ -429,16 +429,16 @@ curl -vi -X DELETE \ -H "Content-Type: text/xml" \ -d 'TmV3R3V5' \ "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 +/_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 targeted version + 1`. Anything else is the same as those in `Conditional Deleting a Row`. |curl -vi -X DELETE \ @@ -446,12 +446,12 @@ curl -vi -X DELETE \ -H "Content-Type: text/xml" \ -d 'TmV3R3V5' \ "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" + "http://example.com:8000/users/row1/cfa:alias/1519423552160/?check=delete" |=== [[xml_schema]] === REST XML Schema -- 2.13.1.windows.2 From 8cb2c9bbb8edc582091f4fa3da9051fefd3fd040 Mon Sep 17 00:00:00 2001 From: Dequan Chen Date: Mon, 16 Apr 2018 13:55:33 -0500 Subject: [PATCH 3/5] Modify the new Endpoint of Check-And-PUT Rest Documentation to have detailed explanation and critical values in monospaced font for JIRA - HBASE-7129 --- src/main/asciidoc/_chapters/external_apis.adoc | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/src/main/asciidoc/_chapters/external_apis.adoc b/src/main/asciidoc/_chapters/external_apis.adoc index dd8eaf0844..0814a81ec6 100644 --- a/src/main/asciidoc/_chapters/external_apis.adoc +++ b/src/main/asciidoc/_chapters/external_apis.adoc @@ -354,7 +354,6 @@ curl -vi -X PUT \ |=== - .Endpoints for `Check-And-Put` Operations [options="header", cols="2m,m,3d,6l"] |=== @@ -365,7 +364,7 @@ curl -vi -X PUT \ |/_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 argument, with check column qualifier and value at the end or right after the new column qualifier and value of the same row key. 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`. +|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` or `-d` argument, with `the check cell name (column family:column name) and value` always at the end and right after `the new Put cell name (column family:column name) and value` of the same row key. 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" \ @@ -378,6 +377,17 @@ curl -vi -X PUT \ -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 + + 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"] -- 2.13.1.windows.2 From eba00edf079f23ed0bd59e83aab15c34ff5636d6 Mon Sep 17 00:00:00 2001 From: Dequan Chen Date: Mon, 16 Apr 2018 15:02:09 -0500 Subject: [PATCH 4/5] Modify the new Endpoint of Check-And-PUT Rest Documentation Detailed Explanation to remove the 4 whitespaces for JIRA - HBASE-7129 --- src/main/asciidoc/_chapters/external_apis.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/main/asciidoc/_chapters/external_apis.adoc b/src/main/asciidoc/_chapters/external_apis.adoc index 0814a81ec6..cb7c92fb2c 100644 --- a/src/main/asciidoc/_chapters/external_apis.adoc +++ b/src/main/asciidoc/_chapters/external_apis.adoc @@ -379,10 +379,10 @@ curl -vi -X 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` +*** 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 Note: "cfa" is the column family name and "alias" are the column (qualifier) name for the non-Base64 encoded cell name. -- 2.13.1.windows.2 From f4d77b6379b33bad83b1e578147e88db62ee8435 Mon Sep 17 00:00:00 2001 From: Dequan Chen Date: Tue, 17 Apr 2018 10:29:42 -0500 Subject: [PATCH 5/5] Modify the new Endpoints of Check-And-PUT and Check-And-Delete Rest Documentation to have Mike-Drob-suggested Detailed Explanation sections for JIRA - HBASE-7129 --- src/main/asciidoc/_chapters/external_apis.adoc | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/main/asciidoc/_chapters/external_apis.adoc b/src/main/asciidoc/_chapters/external_apis.adoc index cb7c92fb2c..edcb2304c9 100644 --- a/src/main/asciidoc/_chapters/external_apis.adoc +++ b/src/main/asciidoc/_chapters/external_apis.adoc @@ -384,6 +384,7 @@ Detailed Explanation: 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. @@ -463,6 +464,17 @@ curl -vi -X DELETE \ -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 checkAndPut `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 -- 2.13.1.windows.2