Status
Current state: "WIP/Under DiscussionAccepted"
Discussion thread: N/A
JIRA: N/A
...
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
...
* Recover: API related to Recover
All API access is over HTTPS. All data is sent and received as JSON. The
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. 2. Config:
/api/v1/config/ |
---|
...
server_config | |
---|---|
GET | |
Get value of all configured values overridden on local server config | |
Response
|
...
|
...
|
...
|
...
|
...
/api/v1/config/ |
---|
...
server_config |
---|
PUT |
...
Update |
...
server configuration | |
Parameters
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
Body |
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
...
Response
|
...
|
...
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
3. Ledger:
/api/v1/ledger/delete/ |
---|
...
?ledger_id=<ledger_id> | |
---|---|
DELETE | |
Delete a ledger. | |
Parameters
|
...
|
...
|
...
|
...
|
...
Response
|
...
|
...
|
...
|
...
/api/v1/ledger/list/ |
---|
...
?print_metadata=<metadata> | |
---|---|
GET | |
List all the ledgers | |
Parameters
|
...
|
...
|
...
|
...
|
...
Response
|
...
|
...
|
...
|
...
|
/api/v1/ledger/metadata/ |
---|
...
?ledger_id=<ledger_id> | |
---|---|
GET | |
Get the metadata of a ledger | |
Parameters
|
...
|
...
|
...
|
...
|
...
Response
|
...
|
...
|
...
|
...
|
/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
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
Response
|
...
|
...
|
...
|
...
|
4. Bookies
/api/v1/ |
---|
...
bookie/list_bookies/?type=<type>&print_hostnames=<hostnames> |
---|
GET |
Get all the available bookies. |
...
PUT
...
Parameters
|
...
|
...
|
...
|
ledger_id Long Yes ledger id of the ledger
...
Response
|
...
|
...
|
...
|
...
|
...
404 Ledger not found
...
/api/v1/bookie/ |
---|
...
list_bookie |
---|
...
_ |
---|
...
info |
---|
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.
...
Get | ||||||
Get bookies disk usage info of this cluster. | ||||||
Response
|
/api/v1/bookie/ |
---|
...
last_ |
---|
...
log_ |
---|
...
mark |
---|
...
GET |
Get |
...
the last log marker. | |
Response
|
...
|
...
|
...
|
/api/v1/bookie/list_disk_ |
---|
...
file/ |
---|
...
?file_type=<type> |
---|
...
GET | |
Get all the files on disk of current bookie. | |
Parameters
|
...
|
...
|
...
|
...
|
...
|
...
Response
|
...
|
...
|
...
|
...
...
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
...
/api/v1/bookie/ |
---|
...
expand_storage | |||
---|---|---|---|
PUT | |||
Expand storage for a bookie. | |||
Response
|
|
...
|
5. Recover
/api/v1/ |
---|
...
autorecovery/bookie/ |
---|
PUT |
Ledger data recovery for failed bookie |
...
Get
...
Parameters
|
...
|
...
|
...
|
...
|
...
journal_id String Yes Journal file name/id.
print_msg Boolean No whether print message body.
Response
Code Description
200 successful operation.
...
|
...
Body
Response
|
|
...
|
...
...
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.
...
/api/v1/ |
---|
...
autorecovery/list_under_replicated_ledger/?missingreplica=<bookie_address>&excludingmissingreplica=<bookie_address> | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
GET | |||||||||||||||||
Get all under replicated ledgers. | |||||||||||||||||
Parameters
Response
|
|
...
|
/api/v1/ |
---|
...
autorecovery/who_is_auditor | |
---|---|
GET | |
Get auditor bookie id. | |
Response
|
...
|
...
|
...
|
...
|
...
/api/v1/ |
---|
...
autorecovery/ |
---|
...
trigger_audit | |
---|---|
PUT | |
Force trigger audit by resting the lostBookieRecoveryDelay. | |
Response
|
...
|
...
|
...
|
...
|
...
/api/v1/ |
---|
...
autorecovery/lost_bookie_recovery_delay | |
---|---|
GET | |
Get lostBookieRecoveryDelay value in seconds. | |
Response
|
...
|
...
|
...
|
...
|
...
/api/v1/ |
---|
...
autorecover/lost_bookie_recovery_delay |
---|
...
...
PUT | |
Set lostBookieRecoveryDelay value in seconds. | |
Parameters
|
...
|
...
|
...
|
...
Body
Response
|
...
|
...
|
...
|
...
|
...
/api/v1/ |
---|
...
autorecovery/decommission |
---|
...
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
...
PUT |
Decommission Bookie, Force trigger Audittask and make sure all the ledgers stored in the decommissioning bookie are replicated. |
...
Parameters
Body
Response
|
|
...
|
...
|
Compatibility, Deprecation, and Migration Plan
...