Issue 674: Documentation for HTTP endpoints #721
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,317 @@ | ||
| --- | ||
| title: BookKeeper http endpoints | ||
|
There was a problem hiding this comment. I would suggest changing "http endpoint" to "Admin REST API", which would be more accurate. |
||
| --- | ||
|
|
||
| This document is to introducing BookKeeper http endpoints that could be used for BookKeeper administration. | ||
|
There was a problem hiding this comment. This document introduces BookKeeper HTTP endpoints, which can be used ... There was a problem hiding this comment. Thanks, will change it. |
||
| If user want to use this feature, parameter "httpServerEnabled" need to be set to "true" in file conf/bk_server.conf. | ||
|
There was a problem hiding this comment. To use this feature, set "httpServerEnabled" to "true" in file conf/bk_server.conf. There was a problem hiding this comment. Thanks, wll change it. |
||
|
|
||
| ## All the endpoints | ||
|
|
||
| Currently all the http endpoints could be divided into these 4 components: | ||
|
There was a problem hiding this comment. The HTTP endpoints are divided into the following groups: There was a problem hiding this comment. Perhaps they should be grouped by endpoints which are bookie specific and those which are for the whole cluster. There was a problem hiding this comment. Thanks. will change the words. There was a problem hiding this comment. HTTP should be capitalized when used in sentences |
||
| 1. Heartbeat: heartbeat for a specific bookie. | ||
| 1. Config: doing the server configuration for a specific bookie. | ||
| 1. Ledger: http endpoints related to ledgers. | ||
| 1. Bookie: http endpoints related to bookies. | ||
| 1. AutoRecovery: http endpoints related to auto recovery. | ||
|
|
||
| ## Heartbeat | ||
|
|
||
| ### Endpoint: /heartbeat | ||
| * Method: GET | ||
| * Description: Get heartbeat status for a specific bookie | ||
| * Response: | ||
|
|
||
| | Code | Description | | ||
| |:-------|:------------| | ||
| |200 | Successful operation | | ||
|
|
||
| ## Config | ||
|
|
||
| ### Endpoint: /api/v1/config/server_config | ||
|
There was a problem hiding this comment. The format of the response should be included in each call. There was a problem hiding this comment. Thanks. the response is construct of code and body, and some of the command the response body not contains too much info. Will add the useful respone body format. |
||
| 1. Method: GET | ||
| * Description: Get value of all configured values overridden on local server config | ||
| * Response: | ||
|
|
||
| | Code | Description | | ||
| |:-------|:------------| | ||
| |200 | Successful operation | | ||
| |403 | Don't have permission | | ||
|
|
||
| |404 | Error handling | | ||
|
There was a problem hiding this comment. What does "Error handling" mean? Shouldn't this be "Not found"? |
||
| 1. Method: PUT | ||
|
There was a problem hiding this comment. Is there already an admin command to do this? Does this access a config in zookeeper or on the local disk? There was a problem hiding this comment. seems not command for this. it only update the inmemory value, which could be used for later ops. There was a problem hiding this comment. I'm not sure it's wise to expose functionality like this at all. It's just asking for people to change configuration in an uncontrolled and unpredictable manner. Was there a driving use case to add this to the http endpoints? There was a problem hiding this comment. @ivankelly I think http endpoints (and configuration service) was introduced by twitter initially and Jia extended it to cover all admin commands. I can see this is useful on dynamic configurations. but Twitter folks can chime in more on the use cases. BTW If there is a question on a feature whether this should be included or not, we should probably be discussing a bit earlier on the coding pull request, rather than later on the documentation pull request. (for future improvements) |
||
| * Description: Update a local server config | ||
| * Parameters: | ||
|
|
||
| | Name | Type | Required | Description | | ||
| |:-----|:-----|:---------|:------------| | ||
| |configName | String | Yes | Configuration name(key) | | ||
| |configValue | String | Yes | Configuration value(value) | | ||
| * Body: | ||
| ```json | ||
| { | ||
| "configName1": "configValue1", | ||
| "configName2": "configValue2" | ||
| } | ||
| ``` | ||
| * Response: | ||
|
|
||
| | Code | Description | | ||
| |:-------|:------------| | ||
| |200 | Successful operation | | ||
| |403 | Don't have permission | | ||
| |404 | Error handling | | ||
|
|
||
| ## Ledger | ||
|
|
||
| ### Endpoint: /api/v1/ledger/delete/?ledger_id=<ledger_id> | ||
| 1. Method: DELETE | ||
| * Description: Delete 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 | Error handling | | ||
|
|
||
| ### Endpoint: /api/v1/ledger/list/?print_metadata=<metadata> | ||
| 1. Method: GET | ||
| * Description: 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 | Error handling | | ||
|
|
||
| ### Endpoint: /api/v1/ledger/metadata/?ledger_id=<ledger_id> | ||
| 1. Method: GET | ||
| * Description: 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 | Error handling | | ||
|
|
||
| ### Endpoint: /api/v1/ledger/read/?ledger_id=<ledger_id>&start_entry_id=<start_entry_id>&end_entry_id=<end_entry_id> | ||
| 1. Method: GET | ||
|
There was a problem hiding this comment. What format are these entries returned in? There was a problem hiding this comment. thanks. will add the format |
||
| * Description: 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 | Error handling | | ||
|
|
||
| ## Bookie | ||
|
|
||
| ### Endpoint: /api/v1/bookie/list_bookies/?type=<type>&print_hostnames=<hostnames> | ||
| 1. Method: GET | ||
| * Description: Get all the available bookies. | ||
| * Parameters: | ||
|
|
||
| | Name | Type | Required | Description | | ||
| |:-----|:-----|:---------|:------------| | ||
| |type | String | Yes | value: rw/ro , list read-write/read-only bookies. | | ||
|
There was a problem hiding this comment. rw/ro is the value? or rw or ro? There was a problem hiding this comment. will change to "rw or ro" |
||
| |print_hostnames | Boolean | No | whether print hostname of bookies. | | ||
| * Response: | ||
|
|
||
| | Code | Description | | ||
| |:-------|:------------| | ||
| |200 | Successful operation | | ||
| |403 | Don't have permission | | ||
| |404 | Error handling | | ||
|
|
||
| ### Endpoint: /api/v1/bookie/list_bookie_info | ||
| 1. Method: GET | ||
| * Description: Get bookies disk usage info of this cluster. | ||
| * Response: | ||
|
|
||
| | Code | Description | | ||
| |:-------|:------------| | ||
| |200 | Successful operation | | ||
| |403 | Don't have permission | | ||
| |404 | Error handling | | ||
|
|
||
| ### Endpoint: /api/v1/bookie/last_log_mark | ||
| 1. Method: GET | ||
| * Description: Get the last log marker. | ||
| * Response: | ||
|
|
||
| | Code | Description | | ||
| |:-------|:------------| | ||
| |200 | Successful operation | | ||
| |403 | Don't have permission | | ||
| |404 | Error handling | | ||
|
|
||
| ### Endpoint: /api/v1/bookie/list_disk_file/?file_type=<type> | ||
| 1. Method: GET | ||
| * Description: 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 | | ||
| |404 | Error handling | | ||
|
|
||
| ### Endpoint: /api/v1/bookie/expand_storage | ||
| 1. Method: PUT | ||
| * Description: Expand storage for a bookie. | ||
| * Response: | ||
|
|
||
| | Code | Description | | ||
| |:-------|:------------| | ||
| |200 | Successful operation | | ||
| |403 | Don't have permission | | ||
| |404 | Error handling | | ||
|
|
||
| ## Auto recovery | ||
|
|
||
| ### Endpoint: /api/v1/autorecovery/bookie/ | ||
| 1. Method: PUT | ||
| * Description: Ledger data recovery for failed bookie | ||
| * Body: | ||
| ```json | ||
| { | ||
| "bookie_src": [ "bookie_src1", "bookie_src2"... ], | ||
| "bookie_dest": [ "bookie_dest1", "bookie_dest2"... ], | ||
| "delete_cookie": <bool_value> | ||
| } | ||
| ``` | ||
| * Parameters: | ||
|
|
||
| | Name | Type | Required | Description | | ||
| |:-----|:-----|:---------|:------------| | ||
| |bookie_src | String | Yes | bookie source to recovery | | ||
|
There was a problem hiding this comment. String or array of strings? There was a problem hiding this comment. Should the strings have a specific format? There was a problem hiding this comment. strings of host names or IP:Port |
||
| |bookie_dest | String | No | bookie data recovery destination | | ||
| |delete_cookie | Boolean | No | Whether delete cookie | | ||
| * Response: | ||
|
|
||
| | Code | Description | | ||
| |:-------|:------------| | ||
| |200 | Successful operation | | ||
| |403 | Don't have permission | | ||
| |404 | Error handling | | ||
|
|
||
| ### Endpoint: /api/v1/autorecovery/list_under_replicated_ledger/?missingreplica=<bookie_address>&excludingmissingreplica=<bookie_address> | ||
| 1. Method: GET | ||
| * Description: Get all under replicated ledgers. | ||
| * Parameters: | ||
|
|
||
| | Name | Type | Required | Description | | ||
| |:-----|:-----|:---------|:------------| | ||
| |missingreplica | String | No | missing replica bookieId | | ||
|
There was a problem hiding this comment. These parameters should have underscores between words to be consistent. There was a problem hiding this comment. @ivankelly I think this is a documentation for what existed. if the parameters should be changed, we should create an issue for it. |
||
| |excludingmissingreplica | String | No | exclude missing replica bookieId | | ||
| * Response: | ||
|
|
||
| | Code | Description | | ||
| |:-------|:------------| | ||
| |200 | Successful operation | | ||
| |403 | Don't have permission | | ||
| |404 | Error handling | | ||
|
|
||
| ### Endpoint: /api/v1/autorecovery/who_is_auditor | ||
| 1. Method: GET | ||
| * Description: Get auditor bookie id. | ||
| * Response: | ||
|
|
||
| | Code | Description | | ||
| |:-------|:------------| | ||
| |200 | Successful operation | | ||
| |403 | Don't have permission | | ||
| |404 | Error handling | | ||
|
|
||
| ### Endpoint: /api/v1/autorecovery/trigger_audit | ||
| 1. Method: PUT | ||
| * Description: Force trigger audit by resting the lostBookieRecoveryDelay. | ||
| * Response: | ||
|
|
||
| | Code | Description | | ||
| |:-------|:------------| | ||
| |200 | Successful operation | | ||
| |403 | Don't have permission | | ||
| |404 | Error handling | | ||
|
|
||
| ### Endpoint: /api/v1/autorecovery/lost_bookie_recovery_delay | ||
| 1. Method: GET | ||
| * Description: Get lostBookieRecoveryDelay value in seconds. | ||
| * Response: | ||
|
|
||
| | Code | Description | | ||
| |:-------|:------------| | ||
| |200 | Successful operation | | ||
| |403 | Don't have permission | | ||
| |404 | Error handling | | ||
| 1. Method: PUT | ||
| * Description: Set lostBookieRecoveryDelay value in seconds. | ||
| * Body: | ||
| ```json | ||
| { | ||
| "delay_seconds": <delay_seconds> | ||
| } | ||
| ``` | ||
| * Parameters: | ||
|
|
||
| | Name | Type | Required | Description | | ||
| |:-----|:-----|:---------|:------------| | ||
| | delay_seconds | Long | Yes | set delay value in seconds. | | ||
| * Response: | ||
|
|
||
| | Code | Description | | ||
| |:-------|:------------| | ||
| |200 | Successful operation | | ||
| |403 | Don't have permission | | ||
| |404 | Error handling | | ||
|
|
||
| ### Endpoint: /api/v1/autorecovery/decommission | ||
| 1. Method: PUT | ||
| * Description: Decommission Bookie, Force trigger Audit task and make sure all the ledgers stored in the decommissioning bookie are replicated. | ||
| * Body: | ||
| ```json | ||
| { | ||
| "bookie_src": <bookie_src> | ||
| } | ||
| ``` | ||
| * Parameters: | ||
|
|
||
| | Name | Type | Required | Description | | ||
| |:-----|:-----|:---------|:------------| | ||
| | bookie_src | String | Yes | Bookie src to decommission.. | | ||
| * Response: | ||
|
|
||
| | Code | Description | | ||
| |:-------|:------------| | ||
| |200 | Successful operation | | ||
| |403 | Don't have permission | | ||
| |404 | Error handling | | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Capitalize HTTP
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
“endpoints” instead of “endpoint”
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
thanks. will follow @sijie 's comments