You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 7 Next »

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>

 

2. Root endpoint:

/api/v1
GET
Get all the available endpoints

Response

CodeDescription
200successful operation
403Don't have permission

 

3. Config:

/api/v1/config/values

GET

Get value of all configured values overridden on local config

Response

CodeDescription
200successful operation
403

Don't have permission

404Configuration not found


/api/v1/config/:configName/:configValue

POST
Update configuration

Parameters

NameTypeRequiredDescription
configNameStringYesConfiguration name(key) 
configValueStringYesConfiguration value(value)

Response

CodeDescription
204successful operation
403

Don't have permission

404Configuration not found

 

4. Bookkeeper:

/api/v1/bookkeeper/format_metadata/:force

POST

Format bookkeeper metadata

Parameters

NameTypeRequiredDescription
forcebooleanNowhether to force format and delete the old data 

Response

CodeDescription
204successful operation
403

Don't have permission

/api/v1/bookkeeper/list_bookies/:type/:hostnames

GET
 Get all the available bookies.

Parameters

NameTypeRequiredDescription
typeStringYes

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

HostnamesBooleanNo whether print hostname of bookie  

Response

CodeDescription
200successful operation
403

Don't have permission

/api/v1/bookkeeper/update_cookie/:idType

POST

Update bookie id in cookie.

Parameters

NameTypeRequiredDescription
idTypeStringYes

 value:  hostname/ip ,  Id by hostname or IP address 

Response

CodeDescription
204successful operation
403

Don't have permission

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

NameTypeRequiredDescription
ensemble_sizeIntYes

 ensemble size 

write_quorum_sizeIntYes

 write quorum size

ack_quorum_sizeIntYes

 ack quorum size

digest_typeStringYes MAC or CRC32
passwordStringYespassword

Response

CodeDescription
200successful created, return ledger_id.
403

Don't have permission

404No ledger found

/api/v1/ledger/delete/:ledger_id

DELETE
Delete a ledger.

Parameters

NameTypeRequiredDescription
ledger_idLongYes

 ledger id of the ledger. 

Response

CodeDescription
403

Don't have permission

404No ledger found

/api/v1/ledger/list/: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

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

404No ledger found

/api/v1/ledger/read/:ledger_id/:start_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

404No ledger found

/api/v1/ledger/read/:ledger_id/:entry_data

PUT
Write a entry to ledger

Parameters

NameTypeRequiredDescription
ledger_idLongYes

 ledger id of the ledger 

entry_data
StringYes

 data to be written to ledger

Response

Code

Description

204successful operation.
403

Don't have permission

404No ledger found

 

6. Bookies

/api/v1/bookie/format_bookie/:delete_cookie

PUT

Format a bookie.

Parameters

NameTypeRequiredDescription
delete_cookieBooleanNo

 whether delete its cookie on zookeeper.

Response

Code

Description

204successful operation.
403

Don't have permission

/api/v1/bookie/list_bookie_info

Get

Get current bookie disk usage.

Response

Code

Description

200successful operation.
403

Don't have permission

/api/v1/bookie/list_disk_files/: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/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/format_bookie/:delete_cookie

PUT

Format a bookie.

Parameters

NameTypeRequiredDescription
delete_cookieBooleanNo

 whether delete its cookie on zookeeper.

Response

Code

Description

204successful 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/format_bookie/:delete_cookie

PUT

Format a bookie.

Parameters

NameTypeRequiredDescription
delete_cookieBooleanNo

 whether delete its cookie on zookeeper.

Response

Code

Description

204successful 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/format_bookie/:delete_cookie

PUT

Format a bookie.

Parameters

NameTypeRequiredDescription
delete_cookieBooleanNo

 whether delete its cookie on zookeeper.

Response

Code

Description

204successful operation.
403

Don't have permission

/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/format_bookie/:delete_cookie

PUT

Format a bookie.

Parameters

NameTypeRequiredDescription
delete_cookieBooleanNo

 whether delete its cookie on zookeeper.

Response

Code

Description

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

  • No labels