Skip to content

Commit 25f9070

Browse files
Dequan Chenbusbey
Dequan Chen
authored and
busbey
committed
HBASE-7129 Rest Documentation for check-and operations.
Signed-off-by: Sakthi <sakthivel.azhaku@gmail.com> Signed-off-by: Sean Busbey <busbey@apache.org> (cherry picked from commit 4e46093)
1 parent 8222631 commit 25f9070

File tree

1 file changed

+122
-0
lines changed

1 file changed

+122
-0
lines changed

‎src/main/asciidoc/_chapters/external_apis.adoc

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -353,6 +353,128 @@ curl -vi -X PUT \
353353
"example.com:8000/users/fakerow"
354354
355355
|===
356+
357+
.Endpoints for `Check-And-Put` Operations
358+
[options="header", cols="2m,m,3d,6l"]
359+
|===
360+
|Endpoint
361+
|HTTP Verb
362+
|Description
363+
|Example
364+
365+
|/_table_/_row_key_/?check=put
366+
|PUT
367+
|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`.
368+
|curl -vi -X PUT \
369+
-H "Accept: text/xml" \
370+
-H "Content-Type: text/xml" \
371+
-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>' \
372+
"http://example.com:8000/users/row1/?check=put"
373+
374+
curl -vi -X PUT \
375+
-H "Accept: application/json" \
376+
-H "Content-Type: application/json" \
377+
-d '{"Row":[{"key":"cm93MQ==","Cell":[{"column":"Y2ZhOmFsaWFz","$":"T2xkR3V5"},{"column":"Y2ZhOmFsaWFz", "$":"TmV3R3V5"}] }]}' \
378+
"http://example.com:8000/users/row1/?check=put"
379+
|===
380+
Detailed Explanation:
381+
382+
*** In the above json-format example:
383+
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"`
384+
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"`
385+
3. `"cm93MQ=="` is `the Base-64 for "row1"` for the checkAndPut `row key`
386+
4. `"/?check=put"` after the `"row key" in the request URL` is required for checkAndPut WebHBase operation to work
387+
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
388+
389+
Note: "cfa" is the column family name and "alias" are the column (qualifier) name for the non-Base64 encoded cell name.
390+
391+
*** Basically, the xml-format example is the same as the json-format example, and will not be explained here in detail.
392+
393+
.Endpoints for `Check-And-Delete` Operations
394+
[options="header", cols="2m,m,3d,6l"]
395+
|===
396+
|Endpoint
397+
|HTTP Verb
398+
|Description
399+
|Example
400+
401+
|/_table_/_row_key_/?check=delete
402+
|DELETE
403+
|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`.
404+
|curl -vi -X DELETE \
405+
-H "Accept: text/xml" \
406+
-H "Content-Type: text/xml" \
407+
-d '<?xml version="1.0" encoding="UTF-8" standalone="yes"?><CellSet><Row key="cm93MQ=="><Cell column="Y2ZhOmFsaWFz">TmV3R3V5</Cell></Row></CellSet>' \
408+
"http://example.com:8000/users/row1/?check=delete"
409+
410+
curl -vi -X DELETE \
411+
-H "Accept: application/json" \
412+
-H "Content-Type: application/json" \
413+
-d '{"Row":[{"key":"cm93MQ==","Cell":[{"column":"Y2ZhOmFsaWFz","$":"TmV3R3V5"}]}]}' \
414+
"http://example.com:8000/users/row1/?check=delete"
415+
416+
|/_table_/_row_key_
417+
/_column_family_
418+
/?check=delete
419+
|DELETE
420+
|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`.
421+
|curl -vi -X DELETE \
422+
-H "Accept: text/xml" \
423+
-H "Content-Type: text/xml" \
424+
-d '<?xml version="1.0" encoding="UTF-8" standalone="yes"?><CellSet><Row key="cm93MQ=="><Cell column="Y2ZhOmFsaWFz">TmV3R3V5</Cell></Row></CellSet>' \
425+
"http://example.com:8000/users/row1/cfa/?check=delete"
426+
427+
curl -vi -X DELETE \
428+
-H "Accept: application/json" \
429+
-H "Content-Type: application/json" \
430+
-d '{"Row":[{"key":"cm93MQ==","Cell":[{"column":"Y2ZhOmFsaWFz","$":"TmV3R3V5"}]}]}' \
431+
"http://example.com:8000/users/row1/cfa/?check=delete"
432+
433+
|/_table_/_row_key_
434+
/_column:qualifier_
435+
/?check=delete
436+
|DELETE
437+
|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`.
438+
|curl -vi -X DELETE \
439+
-H "Accept: text/xml" \
440+
-H "Content-Type: text/xml" \
441+
-d '<?xml version="1.0" encoding="UTF-8" standalone="yes"?><CellSet><Row key="cm93MQ=="><Cell column="Y2ZhOmFsaWFz">TmV3R3V5</Cell></Row></CellSet>' \
442+
"http://example.com:8000/users/row1/cfa:alias/?check=delete"
443+
444+
curl -vi -X DELETE \
445+
-H "Accept: application/json" \
446+
-H "Content-Type: application/json" \
447+
-d '{"Row":[{"key":"cm93MQ==","Cell":[{"column":"Y2ZhOmFsaWFz","$":"TmV3R3V5"}]}]}' \
448+
"http://example.com:8000/users/row1/cfa:alias/?check=delete"
449+
450+
|/_table_/_row_key_
451+
/_column:qualifier_
452+
/_version_id_/?check=delete
453+
|DELETE
454+
|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`.
455+
|curl -vi -X DELETE \
456+
-H "Accept: text/xml" \
457+
-H "Content-Type: text/xml" \
458+
-d '<?xml version="1.0" encoding="UTF-8" standalone="yes"?><CellSet><Row key="cm93MQ=="><Cell column="Y2ZhOmFsaWFz">TmV3R3V5</Cell></Row></CellSet>' \
459+
"http://example.com:8000/users/row1/cfa:alias/1519423552160/?check=delete"
460+
461+
curl -vi -X DELETE \
462+
-H "Accept: application/json" \
463+
-H "Content-Type: application/json" \
464+
-d '{"Row":[{"key":"cm93MQ==","Cell":[{"column":"Y2ZhOmFsaWFz","$":"TmV3R3V5"}]}]}' \
465+
"http://example.com:8000/users/row1/cfa:alias/1519423552160/?check=delete"
466+
|===
467+
Detailed Explanation:
468+
469+
*** In the above 4 json-format examples:
470+
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"`
471+
2. `"cm93MQ=="` is `the Base-64 for "row1"` for the checkAndDelete `row key`
472+
3. `"/?check=delete"` at the end of `the request URL` is required for checkAndDelete WebHBase operation to work
473+
4. `"version_id"` in the `request URL` of the last json-format example should be equivalent to the value of `"the timestamp number + 1"`
474+
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
475+
476+
*** Basically, the 4 xml-format examples are the same as the 4 corresponding json-format examples, and will not be explained here in detail.
477+
356478
[[xml_schema]]
357479
=== REST XML Schema
358480

0 commit comments

Comments
 (0)