Status
Current state: "Accepted"
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:
* Config: Do the configuration.
* 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. Config:
/api/v1/config/server_config |
---|
GET |
Get value of all configured values overridden on local server config |
Response Code | Description |
---|
200 | successful operation | 403 | Don't have permission | 404 | Error handling |
|
/api/v1/config/server_config |
---|
PUT |
Update server configuration |
Parameters Name | Type | Required | Description |
---|
configName | String | Yes | Configuration name(key) | configValue | String | Yes | Configuration value(value) |
Body { "configName1": "configValue1", "configName2": "configValue2" } |
---|
Response Code | Description |
---|
200 | successful operation | 403 | Don't have permission | 404 | Error handling |
|
3. Ledger:
/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 |
---|
200 | successful operation | 403 | Don't have permission | 404 | Error handling |
|
/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 | Error handling |
|
/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 | Error handling |
|
4. Bookies
/api/v1/bookie/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 bookies |
Response Code | Description |
---|
200 | successful operation | 403 | Don't have permission |
|
/api/v1/bookie/list_bookie_info |
---|
Get |
Get bookies disk usage info of this cluster. |
Response Code | Description |
---|
200 | successful operation. | 403 | Don't have permission |
|
/api/v1/bookie/last_log_mark |
---|
GET |
Get the last log marker. |
Response Code | Description |
---|
200 | successful operation. | 403 | Don't have permission |
|
/api/v1/bookie/list_disk_file/?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/expand_storage |
---|
PUT |
Expand storage for a bookie. |
Response Code | Description |
---|
204 | successful operation. | 403 | Don't have permission |
|
5. Recover
/api/v1/autorecovery/bookie/ |
---|
PUT |
Ledger data recovery for failed bookie |
Parameters Name | Type | Required | Description |
---|
bookie_src | String | Yes | bookie source to recovery | bookie_dest | String | No | 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/list_under_replicated_ledger/?missingreplica=<bookie_address>&excludingmissingreplica=<bookie_address> |
---|
GET |
Get all under replicated ledgers. |
Parameters Name | Type | Required | Description |
---|
missingreplica | String | No | missing replica bookieId | excludingmissingreplica | String | No | exclude missing replica bookieId |
Response Code | Description |
---|
200 | successful operation. | 403 | Don't have permission | 404 | Not found under replication node |
|
/api/v1/autorecovery/who_is_auditor |
---|
GET |
Get auditor bookie id. |
Response Code | Description |
---|
200 | successful operation. | 403 | Don't have permission | 404 | Error handling |
|
/api/v1/autorecovery/trigger_audit |
---|
PUT |
Force trigger audit by resting the lostBookieRecoveryDelay. |
Response Code | Description |
---|
200 | successful operation. | 403 | Don't have permission | 404 | Error handling |
|
/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 |
---|
PUT |
Set lostBookieRecoveryDelay value in seconds. |
Parameters Name | Type | Required | Description |
---|
delay_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 |
---|
PUT |
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 |
|
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