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

Child pages

BP-17: Define BookKeeper public http endpoints

Motivation

Public Interfaces

Proposed Changes

Compatibility, Deprecation, and Migration Plan

Test Plan

Rejected Alternatives