THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
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>
3. Root endpoint:
/api/v1
GET
Get all the available endpoints
Response
Code Description
200 successful operation
403 Don't have permission
4. 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
5. 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 Value Required Description
type String rw/ro Yes list read-write/read-only bookies
Hostnames Boolean yes/no 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 Value Required Description
idType String hostname/ip Yes Id by hostname or IP address
Response
Code Description
204 successful operation
403 Don't have permission
404 Not update, for errors
6. 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 create, 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 Ledger not 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 Ledger not 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 Ledger not 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 Ledger not 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 Ledger not found
7. 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 format.
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
Expend bookie storage.
Response
Code Description
204 successful operation.
403 Don't have permission
8. Recover
/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/:time
POST
Set lostBookieRecoveryDelay value in seconds.
Parameters
Name Type Required Description
Time String 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 ledger
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