Status

Current state: "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

GET

Get value of all configured values overridden on local server config

Response

Code	Description
200	successful operation
403	Don't have permission
404	Configuration not found

/api/v1/config

POST

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
204	successful operation
403	Don't have permission
404	Configuration not found

4. Bookkeeper:

/api/v1/bookkeeper/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 bookie

Response

Code	Description
200	successful operation
403	Don't have permission

/api/v1/bookkeeper/update_cookie/?bookie_id_type=<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/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
403	Don't have permission
404	No ledger found

/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	No ledger found

/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	No ledger found

6. Bookies

/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/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_files/?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/read_entry_log/?print_msg=<print_msg>&ledger_id=<ledger_id>

&entry_id=<entry_id>&start_position=<start_position>&end_positon=<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_dir>&journal_id=<journal_id>&print_msg=<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/expend_storage

POST

Expend storage for a bookie.

Response

Code	Description
204	successful operation.
403	Don't have permission

7. Recover

/api/v1/autorecovery/bookie/

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

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/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/autorecovery/trigger_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/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

POST

Set lostBookieRecoveryDelay value in seconds.

Parameters

Name	Type	Required	Description
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

POST

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

/api/v1/autorecovery/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

Status

Motivation

Public Interfaces

Proposed Changes

Compatibility, Deprecation, and Migration Plan

Test Plan

Rejected Alternatives