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

CodeDescription
200successful operation
403

Don't have permission

404Error handling


/api/v1/config/server_config

PUT
Update server configuration

Parameters

NameTypeRequiredDescription
configNameStringYesConfiguration name(key) 
configValueStringYesConfiguration value(value)

Body

{
    "configName1": "configValue1",
    "configName2": "configValue2"
}


Response

CodeDescription
200successful operation
403

Don't have permission

404Error handling

 

3. Ledger:

 

/api/v1/ledger/delete/?ledger_id=<ledger_id>

DELETE
Delete a ledger.

Parameters

NameTypeRequiredDescription
ledger_idLongYes

 ledger id of the ledger. 

Response

Code

Description

200successful operation
403

Don't have permission

404Error handling

/api/v1/ledger/list/?print_metadata=<metadata>

GET

List all the ledgers

Parameters

NameTypeRequiredDescription
metadataBooleanNo

 whether print out metadata 

Response

Code

Description

200successful operation.
403

Don't have permission

404No ledger found

/api/v1/ledger/metadata/?ledger_id=<ledger_id>

GET

Get the metadata of a ledger

Parameters

NameTypeRequiredDescription
ledger_idLongYes

 ledger id of the ledger 

Response

Code

Description

200successful operation.
403

Don't have permission

404Error 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

NameTypeRequiredDescription
ledger_idLongYes

 ledger id of the ledger 

start_entry_idLongNo

 start entry id of read range

end_entry_idLongNo

 end entry id of read range

Response

Code

Description

200successful operation.
403

Don't have permission

404Error handling

 

4. Bookies

/api/v1/bookie/list_bookies/?type=<type>&print_hostnames=<hostnames>

GET
 Get all the available bookies.

Parameters

NameTypeRequiredDescription
typeStringYes

 value: rw/ro , list read-write/read-only bookies 

hostnamesBooleanNo whether print hostname of bookies

Response

CodeDescription
200successful operation
403

Don't have permission

/api/v1/bookie/list_bookie_info

Get

Get bookies disk usage info of this cluster.

Response

Code

Description

200successful operation.
403

Don't have permission

/api/v1/bookie/last_log_mark

GET

Get the last log marker.

Response

Code

Description

200successful 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

NameTypeRequiredDescription
typeStringNo

  file type: journal/entrylog/index.

Response

Code

Description

200successful operation.
403

Don't have permission

/api/v1/bookie/expand_storage

PUT

Expand storage for a bookie.

Response

Code

Description

204successful operation.
403

Don't have permission

 

 

5. Recover

/api/v1/autorecovery/bookie/

PUT
Ledger data recovery for failed bookie

Parameters

NameTypeRequiredDescription
bookie_srcStringYesbookie source to recovery
bookie_destStringNobookie data recovery destination
delete_cookieBooleanNoWhether delete cookie

Body

{
  "bookie_src": [ "bookie_src1", "bookie_src2"... ],

 "bookie_dest": [ "bookie_dest1", "bookie_dest2"... ],

 "delete_cookie": <bool_value>

}

Response

Code

Description

200successful operation.
403

Don't have permission

404Not found Bookie

/api/v1/autorecovery/list_under_replicated_ledger/?missingreplica=<bookie_address>&excludingmissingreplica=<bookie_address>

GET
Get all under replicated ledgers.

Parameters

NameTypeRequiredDescription
missingreplicaStringNomissing replica bookieId
excludingmissingreplicaStringNoexclude missing replica bookieId


Response

Code

Description

200successful operation.
403

Don't have permission

404Not found under replication node

/api/v1/autorecovery/who_is_auditor

GET
Get auditor bookie id.

Response

Code

Description

200successful operation.
403

Don't have permission

404Error handling

/api/v1/autorecovery/trigger_audit

PUT
Force trigger audit by resting the lostBookieRecoveryDelay.

Response

Code

Description

200successful operation.
403

Don't have permission

404Error handling

/api/v1/autorecovery/lost_bookie_recovery_delay

GET
Get lostBookieRecoveryDelay value in seconds.

Response

Code

Description

200successful operation.
403

Don't have permission

404Not found under replication node

/api/v1/autorecover/lost_bookie_recovery_delay

PUT

Set lostBookieRecoveryDelay value in seconds.

Parameters

NameTypeRequiredDescription
delay_seconds
LongYes

 set delay value in seconds.

Body

{
 "delay_seconds": <delay_seconds>

}

Response

Code

Description

204successful operation.
403

Don't have permission

404Not 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

NameTypeRequiredDescription
bookie_srcStringYes

 Bookie src to decommission.

Body

{
  "bookie_src": bookie_src,

}

Response

Code

Description

204successful operation.
403

Don't have permission

404Not 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

  • No labels