You are viewing an old version of this page. View the current version.
Compare with Current
View Page History
« Previous
Version 9
Next »
tatus
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/:configName/:configValue |
---|
POST |
Update configuration |
Parameters Name | Type | Required | Description |
---|
configName | String | Yes | Configuration name(key) | configValue | String | Yes | Configuration value(value) |
Response Code | Description |
---|
204 | successful operation | 403 | Don't have permission | 404 | Configuration not found |
|
4. Bookkeeper:
/api/v1/bookkeeper/format_metadata/:force |
---|
POST |
Format bookkeeper metadata |
Parameters Name | Type | Required | Description |
---|
force | boolean | No | whether to force format and delete the old data |
Response Code | Description |
---|
204 | successful operation | 403 | Don't have permission |
|
/api/v1/bookkeeper/list_bookies/:type/: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/: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/:ensemble_size/:write_quorum_size/:ack_quorum_size/:digest_type/:password |
---|
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 |
Response Code | Description |
---|
200 | successful created, return ledger_id. | 403 | Don't have permission | 404 | No ledger found |
|
/api/v1/ledger/delete/: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/: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 |
---|
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/:start_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 |
|
/api/v1/ledger/read/:ledger_id/:entry_data |
---|
PUT |
Write a entry to ledger |
Parameters Name | Type | Required | Description |
---|
ledger_id | Long | Yes | ledger id of the ledger | entry_data
| String | Yes | data to be written to ledger |
Response Code | Description |
---|
204 | successful operation. | 403 | Don't have permission | 404 | No ledger found |
|
6. Bookies
/api/v1/bookie/format_bookie/: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/: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/:ledger_id/:entry_id/:start_position/: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_id/: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/recover/bookie/:bookie_src/:bookie_dest/:delete_cookie |
---|
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 |
Response Code | Description |
---|
200 | successful operation. | 403 | Don't have permission | 404 | Not found Bookie |
|
/api/v1/recover/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/recover/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/recover/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/recover/lost_bookie_recovery_delay/:seconds |
---|
POST |
Set lostBookieRecoveryDelay value in seconds. |
Parameters Name | Type | Required | Description |
---|
seconds | Long | Yes | set delay value in seconds. |
Response Code | Description |
---|
204 | successful operation. | 403 | Don't have permission | 404 | Not found under replication node |
|
/api/v1/recover/decommission |
---|
POST |
Decommission Bookie, Force trigger Audittask and make sure all the ledgers stored in the decommissioning bookie are replicated. |
Response Code | Description |
---|
204 | successful operation. | 403 | Don't have permission | 404 | Not found under replication node |
|
/api/v1/recover/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