You are viewing an old version of this page. View the current version.
Compare with Current
View Page History
« Previous
Version 14
Next »
Status
Current state: "WIP/Under Discussion"
Discussion thread: N/A
JIRA: N/A
Released: 4.6.0
Motivation
Github #278 introduces BookKeeper Http Endpoint module. However there are only two endpoints, which is “/heartbeat” and “/api/config/serverConfig”, defined in #278. In order to fully leverage the http modules, The goal is to add more endpoints to this modules.
Public Interfaces
N/A
Proposed Changes
1, Overview
Provide Http EndPoints for these components:
* Components:
* Root endpoint: List all the available endpoints
* Config: Do the configuration.
* Bookkeeper : API related to BookKeeper.
* Ledger: API related to ledgers
* Bookie: API related to Bookie
* Recover: API related to Recover
All API access is over HTTPS. All data is sent and received as JSON.
The common REST API Pattern will be:
/api/v1/<component>/<action>
2. Root endpoint:
/api/v1 |
---|
GET |
Get all the available endpoints |
Response Code | Description |
---|
200 | successful operation | 403 | Don't have permission |
|
3. Config:
/api/v1/config/values |
---|
GET |
Get value of all configured values overridden on local config |
Response Code | Description |
---|
200 | successful operation | 403 | Don't have permission | 404 | Configuration not found |
|
/api/v1/config |
---|
POST |
Update configuration |
Parameters Name | Type | Required | Description |
---|
configName | String | Yes | Configuration name(key) | configValue | String | Yes | Configuration value(value) |
Body { "configs": { "configName1": "configValue1", "configName2": "configValue2" } } |
---|
Response Code | Description |
---|
204 | successful operation | 403 | Don't have permission | 404 | Configuration not found |
|
4. Bookkeeper:
/api/v1/bookkeeper/list_bookies/?type=<type>&print_hostnames=<hostnames> |
---|
GET |
Get all the available bookies. |
Parameters Name | Type | Required | Description |
---|
type | String | Yes | value: rw/ro , list read-write/read-only bookies | hostnames | Boolean | No | whether print hostname of bookie |
Response Code | Description |
---|
200 | successful operation | 403 | Don't have permission |
|
/api/v1/bookkeeper/update_cookie/?bookie_id_type=<idType> |
---|
POST |
Update bookie id in cookie. |
Parameters Name | Type | Required | Description |
---|
idType | String | Yes | value: hostname/ip , Id by hostname or IP address |
Response Code | Description |
---|
204 | successful operation | 403 | Don't have permission | 404 | Not update, for errors |
|
5. Ledger:
/api/v1/ledger/create/ |
---|
PUT |
Create a ledger. |
Parameters Name | Type | Required | Description |
---|
ensemble_size | Int | Yes | ensemble size | write_quorum_size | Int | Yes | write quorum size | ack_quorum_size | Int | Yes | ack quorum size | digest_type | String | Yes | MAC or CRC32 | password | String | Yes | password | medadata | <String, String> | No | custom metadata |
Body { "ensemble_size": <int_value>, "write_quorum_size": <int_value>, "ack_quorum_size": <int_value>, "digest_type": "MAC", "password": <password_string>, "medadata": { "configName1": "configValue1", "configName2": "configValue2" } } |
---|
Response Code | Description |
---|
200 | successful created, return ledger_id. | 403 | Don't have permission | 404 | No ledger found |
|
/api/v1/ledger/delete/?ledger_id=<ledger_id> |
---|
DELETE |
Delete a ledger. |
Parameters Name | Type | Required | Description |
---|
ledger_id | Long | Yes | ledger id of the ledger. |
Response Code | Description |
---|
403 | Don't have permission | 404 | No ledger found |
|
/api/v1/ledger/list/?print_metadata=<metadata> |
---|
GET |
List all the ledgers |
Parameters Name | Type | Required | Description |
---|
metadata | Boolean | No | whether print out metadata |
Response Code | Description |
---|
200 | successful operation. | 403 | Don't have permission | 404 | No ledger found |
|
/api/v1/ledger/metadata/?ledger_id=<ledger_id> |
---|
GET |
Get the metadata of a ledger |
Parameters Name | Type | Required | Description |
---|
ledger_id | Long | Yes | ledger id of the ledger |
Response Code | Description |
---|
200 | successful operation. | 403 | Don't have permission | 404 | No ledger found |
|
/api/v1/ledger/read/?ledger_id=<ledger_id>&start_entry_id=<start_entry_id>&end_entry_id=<end_entry_id> |
---|
GET |
Read a range of entries from ledger |
Parameters Name | Type | Required | Description |
---|
ledger_id | Long | Yes | ledger id of the ledger | start_entry_id | Long | No | start entry id of read range | end_entry_id | Long | No | end entry id of read range |
Response Code | Description |
---|
200 | successful operation. | 403 | Don't have permission | 404 | No ledger found |
|
6. Bookies
/api/v1/bookie/format_bookie/?delete_cookie=<delete_cookie> |
---|
PUT |
Format a bookie. |
Parameters Name | Type | Required | Description |
---|
delete_cookie | Boolean | No | whether delete its cookie on zookeeper. |
Response Code | Description |
---|
204 | successful operation. | 403 | Don't have permission |
|
/api/v1/bookie/list_bookie_info |
---|
Get |
Get current bookie disk usage. |
Response Code | Description |
---|
200 | successful operation. | 403 | Don't have permission |
|
/api/v1/bookie/list_disk_files/?file_type=<type> |
---|
GET |
Get all the files on disk of current bookie. |
Parameters Name | Type | Required | Description |
---|
type | String | No | file type: journal/entrylog/index. |
Response Code | Description |
---|
200 | successful operation. | 403 | Don't have permission |
|
/api/v1/bookie/read_entry_log/?print_msg=<print_msg>&ledger_id=<ledger_id> &entry_id=<entry_id>&start_position=<start_position>&end_positon=<end_positon> |
---|
GET |
Read entry log content from entry log files. |
Parameters Name | Type | Required | Description |
---|
print_msg | Boolean | No | whether print message body. | ledger_id | Long | No | only read content of this ledger_id. | entry_id | Long | No | entry_id to read.. | start_position | Long | No | start position to read | end_positon | Long | No | end position of read |
Response Code | Description |
---|
200 | successful operation. | 403 | Don't have permission |
|
/api/v1/bookie/read_journal_file/?journal_dir=<journal_dir>&journal_id=<journal_id>&print_msg=<print_msg> |
---|
GET |
Read journal fie content from disk. |
Parameters Name | Type | Required | Description |
---|
journal_dir | String | Yes | Journal directory | journal_id | String | Yes | Journal file name/id. | print_msg | Boolean | No | whether print message body. |
Response Code | Description |
---|
200 | successful operation. | 403 | Don't have permission | 404 | File not found |
|
/api/v1/bookie/print_last_log_mark |
---|
GET |
Get the last log marker. |
Response Code | Description |
---|
200 | successful operation. | 403 | Don't have permission |
|
/api/v1/bookie/expend_storage |
---|
POST |
Format a bookie. |
Response Code | Description |
---|
204 | successful operation. | 403 | Don't have permission |
|
7. Recover
/api/v1/autorecovery/bookie/ |
---|
POST |
Ledger data recovery for failed bookie |
Parameters Name | Type | Required | Description |
---|
bookie_src | String | Yes | bookie source to recovery | bookie_dest | String | Yes | bookie data recovery destination | delete_cookie | Boolean | No | Whether delete cookie |
Body { "bookie_src": [ bookie_src1, bookie_src2... ], "bookie_dest": [ bookie_dest1, bookie_dest2... ], "delete_cookie": <bool_value> } |
---|
Response Code | Description |
---|
200 | successful operation. | 403 | Don't have permission | 404 | Not found Bookie |
|
/api/v1/autorecovery/who_is_auditor |
---|
GET |
Get auditor id. |
Response Code | Description |
---|
200 | successful operation. | 403 | Don't have permission | 404 | Not found under replication node for auditor |
|
/api/v1/autorecovery/triger_audit |
---|
PUT |
Force trigger audit by resting the lostBookieRecoveryDelay. |
Response Code | Description |
---|
204 | successful operation. | 403 | Don't have permission | 404 | Not found under replication node |
|
/api/v1/autorecovery/lost_bookie_recovery_delay |
---|
GET |
Get lostBookieRecoveryDelay value in seconds. |
Response Code | Description |
---|
200 | successful operation. | 403 | Don't have permission | 404 | Not found under replication node |
|
/api/v1/autorecover/lost_bookie_recovery_delay |
---|
POST |
Set lostBookieRecoveryDelay value in seconds. |
Parameters Name | Type | Required | Description |
---|
seconds | Long | Yes | set delay value in seconds. |
Body { "delay_seconds": <delay_seconds> } |
---|
Response Code | Description |
---|
204 | successful operation. | 403 | Don't have permission | 404 | Not found under replication node |
|
/api/v1/autorecovery/decommission |
---|
POST |
Decommission Bookie, Force trigger Audittask and make sure all the ledgers stored in the decommissioning bookie are replicated. |
Parameters Name | Type | Required | Description |
---|
bookie_src | String | Yes | Bookie src to decommission. |
Body { "bookie_src": bookie_src, } |
---|
Response Code | Description |
---|
204 | successful operation. | 403 | Don't have permission | 404 | Not found under replication node |
|
/api/v1/autorecovery/list_under_replicated_ledger |
---|
GET |
Get all under replicated ledgers. |
Response Code | Description |
---|
200 | successful operation. | 403 | Don't have permission | 404 | Not found under replication node |
|
Compatibility, Deprecation, and Migration Plan
This is a new component introduced in 4.6.0. So there is no migration required. You can still enable http endpint by setting `...` to true.
Test Plan
- Unit test
- will support backward compatibility test in future when there is more version introduced.
Rejected Alternatives
N/A