From 2aefa0d3c91007a480d39d41f6b5e01eab15421c Mon Sep 17 00:00:00 2001 From: Eric Passmore Date: Thu, 15 Sep 2022 13:30:36 -0700 Subject: [PATCH] updated swagger for http production producer plugin --- .../producer_api_plugin/producer.swagger.yaml | 574 ++++++++++-------- 1 file changed, 315 insertions(+), 259 deletions(-) diff --git a/plugins/producer_api_plugin/producer.swagger.yaml b/plugins/producer_api_plugin/producer.swagger.yaml index aea863a798..fdab07368b 100644 --- a/plugins/producer_api_plugin/producer.swagger.yaml +++ b/plugins/producer_api_plugin/producer.swagger.yaml @@ -6,7 +6,7 @@ info: name: MIT url: https://opensource.org/licenses/MIT contact: - url: https://eos.io + url: https://eosnetwork.com tags: - name: eosio servers: @@ -30,259 +30,162 @@ paths: /producer/pause: post: summary: pause - description: Pause producer node + description: Pause producer node. Takes no arguments returns no values. operationId: pause - parameters: [] - requestBody: - content: - application/json: - schema: - type: object - properties: {} responses: - "200": + "201": description: OK content: application/json: schema: - type: boolean - description: "returns status" + $ref: '#/component/schema/OK' /producer/resume: post: summary: resume - description: Resume producer node + description: Resume producer node. Takes no arguments returns no values. operationId: resume - parameters: [] - requestBody: - content: - application/json: - schema: - type: object - description: Resumes activity for producer responses: - "200": + "201": description: OK content: application/json: schema: - description: Returns Nothing + $ref: '#/component/schema/OK' /producer/paused: post: summary: paused - description: Retreives paused status for producer node + description: Retreives paused status for producer node. Takes no arguments returns no values. operationId: paused - parameters: [] - requestBody: - content: - application/json: - schema: - type: object - properties: {} responses: - "200": + "201": description: OK content: application/json: schema: - type: boolean - description: True if producer is paused, false otherwise + $ref: '#/component/schema/OK' /producer/get_runtime_options: post: summary: get_runtime_options - description: Retreives run time options for producer node + description: Retreives run time options for producer node. Only `incoming_defer_ratio` is a floating point number the other return values are signed integers. operationId: get_runtime_options - parameters: [] - requestBody: - content: - application/json: - schema: - type: object - properties: {} responses: - "200": + "201": description: OK content: application/json: schema: - type: object - description: Returns run time options set for the producer - properties: - max_transaction_time: - type: integer - description: Max transaction time - max_irreversible_block_age: - type: integer - description: Max irreversible block age - produce_time_offset_us: - type: integer - description: Time offset - last_block_time_offset_us: - type: integer - description: Last block time offset - max_scheduled_transaction_time_per_block_ms: - type: integer - description: Max scheduled transaction time per block in ms - subjective_cpu_leeway_us: - type: integer - description: Subjective CPU leeway - incoming_defer_ratio: - type: integer - description: Incoming defer ration + $ref: '#/component/schema/Runtime_Options' + /producer/update_runtime_options: post: summary: update_runtime_options - description: Update run time options for producer node + description: Update run time options for producer node. May post any of the runtime options in combination or along. Only `incoming_defer_ratio` is a floating point number the other values are signed integers. operationId: update_runtime_options - parameters: [] requestBody: content: application/json: schema: - type: object - required: - - options - properties: - options: - type: object - description: Defines the run time options to set for the producer - properties: - max_transaction_time: - type: integer - description: Max transaction time - max_irreversible_block_age: - type: integer - description: Max irreversible block age - produce_time_offset_us: - type: integer - description: Time offset - last_block_time_offset_us: - type: integer - description: Last block time offset - max_scheduled_transaction_time_per_block_ms: - type: integer - description: Max scheduled transaction time per block in ms - subjective_cpu_leeway_us: - type: integer - description: Subjective CPU leeway - incoming_defer_ratio: - type: integer - description: Incoming defer ration + $ref: '#/component/schema/Runtime_Options' responses: - "200": + "201": description: OK content: application/json: schema: - description: Returns Nothing + $ref: '#/component/schema/OK' /producer/get_greylist: post: summary: get_greylist - description: Retreives the greylist for producer node + description: Retreives the greylist for producer node. operationId: get_greylist - parameters: [] - requestBody: - content: - application/json: - schema: - type: object - properties: {} responses: - "200": + "201": description: OK content: application/json: schema: - type: array - description: List of account names stored in the greylist - items: - $ref: "https://eosio.github.io/schemata/v2.0/oas/Name.yaml" + type: object + properties: + accounts: + type: array + description: Array of account names stored in the greylist + items: + $ref: "https://eosio.github.io/schemata/v2.0/oas/Name.yaml" /producer/add_greylist_accounts: post: summary: add_greylist_accounts - description: Adds accounts to grey list for producer node + description: Adds accounts to grey list for producer node. At least one account is required. operationId: add_greylist_accounts - parameters: [] requestBody: content: application/json: schema: type: object - required: - - params properties: - params: - type: object - properties: - accounts: - type: array - description: List of account names to add - items: - $ref: "https://eosio.github.io/schemata/v2.0/oas/Name.yaml" + accounts: + type: array + description: List of account names to add + items: + $ref: "https://eosio.github.io/schemata/v2.0/oas/Name.yaml" responses: - "200": + "201": description: OK content: application/json: schema: - description: Returns Nothing + $ref: '#/component/schema/OK' + "400": + description: client error + content: + application/json: + schema: + $ref: '#/component/schema/Error' /producer/remove_greylist_accounts: post: summary: remove_greylist_accounts - description: Removes accounts from greylist for producer node + description: Removes accounts from greylist for producer node. At least one account is required. operationId: remove_greylist_accounts - parameters: [] requestBody: content: application/json: schema: type: object - required: - - params properties: - params: - type: object - properties: - accounts: - type: array - description: List of account names to remove - items: - $ref: "https://eosio.github.io/schemata/v2.0/oas/Name.yaml" + accounts: + type: array + description: List of account names to remove + items: + $ref: "https://eosio.github.io/schemata/v2.0/oas/Name.yaml" responses: - "200": + "201": description: OK content: application/json: schema: - type: array - description: List of account names stored in the greylist - items: - $ref: "https://eosio.github.io/schemata/v2.0/oas/Name.yaml" - + $ref: '#/component/schema/OK' + "400": + description: client error + content: + application/json: + schema: + $ref: '#/component/schema/Error' /producer/get_whitelist_blacklist: post: summary: get_whitelist_blacklist - description: Retreives the white list and black list for producer node + description: Retreives the white list and black list for producer node. A json object containing whitelist and blacklist information. `actor_whitelist` , `actor_blacklist`, `contract_whitelist`, `contract_blacklist` are represented by an array of Names. `action_blacklist` is an array of tuples consisting of Name and Action. `key_blacklist` is an array of Public Keys. Name is a string represeting a NamePrivileged or NameBasic or NameBid or NameCatchAll operationId: get_whitelist_blacklist - parameters: [] - requestBody: - content: - application/json: - schema: - type: object - properties: {} responses: - "200": + "201": description: OK content: application/json: schema: type: object - description: Defines the actor whitelist and blacklist, the contract whitelist and blacklist, the action blacklist and key blacklist properties: actor_whitelist: type: array @@ -317,106 +220,105 @@ paths: /producer/set_whitelist_blacklist: post: summary: set_whitelist_blacklist - description: Sets the white list and black list for producer node + description: Defines the whitelist and blacklist for a producer node. Takes a json object containing whitelist and blacklist information. At least one of actor_whitelist, actor_blacklist, contract_whitelist, contract_blacklist, action_blacklist, and key_blacklist is required. `actor_whitelist` , `actor_blacklist`, `contract_whitelist`, `contract_blacklist` take an array of Names. `action_blacklist` is an array of tuples consisting of Name and Action. `key_blacklist` is an array of Public Keys. Name is a string represeting a NamePrivileged or NameBasic or NameBid or NameCatchAll operationId: set_whitelist_blacklist - parameters: [] + required: true requestBody: content: application/json: schema: type: object - required: - - params properties: - params: - type: object - description: Defines the actor whitelist and blacklist, the contract whitelist and blacklist, the action blacklist and key blacklist - properties: - actor_whitelist: - type: array - items: - $ref: "https://eosio.github.io/schemata/v2.0/oas/Name.yaml" - actor_blacklist: - type: array - items: - $ref: "https://eosio.github.io/schemata/v2.0/oas/Name.yaml" - contract_whitelist: - type: array - items: - $ref: "https://eosio.github.io/schemata/v2.0/oas/Name.yaml" - contract_blacklist: - type: array - items: - $ref: "https://eosio.github.io/schemata/v2.0/oas/Name.yaml" - action_blacklist: - type: array - items: - type: array - description: Array of two string values, the account name as the first and action name as the second - items: - allOf: - - $ref: "https://eosio.github.io/schemata/v2.0/oas/Name.yaml" - - $ref: "https://eosio.github.io/schemata/v2.0/oas/CppSignature.yaml" - key_blacklist: - type: array - items: - $ref: "https://eosio.github.io/schemata/v2.0/oas/KeyType.yaml" - + actor_whitelist: + type: array + items: + $ref: "https://eosio.github.io/schemata/v2.0/oas/Name.yaml" + actor_blacklist: + type: array + items: + $ref: "https://eosio.github.io/schemata/v2.0/oas/Name.yaml" + contract_whitelist: + type: array + items: + $ref: "https://eosio.github.io/schemata/v2.0/oas/Name.yaml" + contract_blacklist: + type: array + items: + $ref: "https://eosio.github.io/schemata/v2.0/oas/Name.yaml" + action_blacklist: + type: array + items: + type: array + description: Array of two string values, the account name as the first and action name as the second + items: + anyOf: + - $ref: "https://eosio.github.io/schemata/v2.0/oas/Name.yaml" + - $ref: "https://eosio.github.io/schemata/v2.0/oas/CppSignature.yaml" + key_blacklist: + type: array + items: + $ref: "https://eosio.github.io/schemata/v2.0/oas/KeyType.yaml" responses: - "200": + "201": description: OK content: application/json: schema: - description: Returns Nothing + $ref: '#/component/schema/OK' + + "400": + description: client error + content: + application/json: + schema: + $ref: '#/component/schema/Error' + /producer/create_snapshot: post: summary: create_snapshot - description: Creates a snapshot for producer node + description: Creates a snapshot for producer node. Returns error when unable to create snapshot. operationId: create_snapshot - parameters: [] - requestBody: - content: - application/json: - schema: - type: object - required: - - next - properties: - next: - type: object - description: Defines the snapshot to be created - properties: - snapshot_name: - type: string - description: The name of the snapshot - head_block_id: - $ref: "https://eosio.github.io/schemata/v2.0/oas/Sha256.yaml" - - responses: - "200": + "201": description: OK content: application/json: schema: - description: Returns Nothing + type: object + properties: + head_block_id: + $ref: "https://eosio.github.io/schemata/v2.0/oas/Sha256.yaml" + head_block_num: + type: integer + descripiton: Highest block number on the chain + example: 5102 + head_block_time: + type: string + description: Highest block unix timestamp + example: 2020-11-16T00:00:00.000 + version: + type: integer + description: version number + example: 6 + snapshot_name: + type: string + description: The path and file name of the snapshot + example: /home/me/nodes/node-name/snapshots/snapshot-0000999f99999f9f999f99f99ff9999f999f9fff99ff99ffff9f9f9fff9f9999.bin + "400": + description: client error + content: + application/json: + schema: + $ref: '#/component/schema/Error' /producer/get_integrity_hash: post: summary: get_integrity_hash description: Retreives the integrity hash for producer node operationId: get_integrity_hash - parameters: [] - requestBody: - content: - application/json: - schema: - type: object - properties: {} responses: - "200": + "201": description: OK content: application/json: @@ -424,69 +326,61 @@ paths: type: object description: Defines the integrity hash information details properties: - integrity_hash: - $ref: "https://eosio.github.io/schemata/v2.0/oas/Sha256.yaml" head_block_id: $ref: "https://eosio.github.io/schemata/v2.0/oas/Sha256.yaml" + integrity_hash: + $ref: "https://eosio.github.io/schemata/v2.0/oas/Sha256.yaml" /producer/schedule_protocol_feature_activations: post: summary: schedule_protocol_feature_activations - description: Schedule protocol feature activation for producer node + description: Schedule protocol feature activation for producer node. Note some features may require pre-activation. Will return error for duplicate requests or when feature required pre-activation. operationId: schedule_protocol_feature_activations - parameters: [] requestBody: content: application/json: schema: type: object - required: - - schedule properties: - schedule: - type: object - properties: - protocol_features_to_activate: - type: array - description: List of protocol features to activate - items: - $ref: "https://eosio.github.io/schemata/v2.0/oas/Sha256.yaml" - + protocol_features_to_activate: + type: array + description: List of protocol features to activate + items: + $ref: "https://eosio.github.io/schemata/v2.0/oas/Sha256.yaml" responses: - "200": + "201": description: OK content: application/json: schema: - description: Returns Nothing + $ref: '#/component/schema/OK' + "400": + description: client error + content: + application/json: + schema: + $ref: '#/component/schema/Error' /producer/get_supported_protocol_features: post: summary: get_supported_protocol_features - description: Retreives supported protocol features for producer node + description: Retreives supported protocol features for producer node. Pass filters in as part of the request body. operationId: get_supported_protocol_features - parameters: [] requestBody: content: application/json: schema: type: object - required: - - params properties: - params: - type: object - description: Defines filters based on which to return the supported protocol features - properties: - exclude_disabled: - type: boolean - description: Exclude disabled protocol features - exclude_unactivatable: - type: boolean - description: Exclude unactivatable protocol features - + exclude_disabled: + type: boolean + description: Exclude disabled protocol features + exclude_unactivatable: + type: boolean + description: Exclude unactivatable protocol features + example: false responses: - "200": + "201": description: OK content: application/json: @@ -494,4 +388,166 @@ paths: type: array description: Variant type, an array of strings with the supported protocol features items: - type: string + type: object + properties: + feature_digest: + $ref: "https://eosio.github.io/schemata/v2.0/oas/Sha256.yaml" + subjective_restrictions: + type: object + properties: + enabled: + type: boolean + example: true + preactivation_required: + type: boolean + example: true + earliest_allowed_activation_time: + type: string + example: "1970-01-01T00:00:00.000" + description_digest: + $ref: "https://eosio.github.io/schemata/v2.0/oas/Sha256.yaml" + dependancies: + type: array + items: + $ref: "https://eosio.github.io/schemata/v2.0/oas/Sha256.yaml" + protocol_feature_type: + type: string + example: "builtin" + specification: + type: array + items: + type: object + properties: + name: + type: string + value: + type: string + + + /producer/get_account_ram_corrections: + post: + summary: get_account_ram_corrections + description: Retreives accounts with ram corrections. + operationId: get_account_ram_corrections + requestBody: + content: + application/json: + schema: + type: object + properties: + lower_bound: + type: int + description: lowest account key + upper_bound: + type: int + description: highest account key + limit: + type: int + description: number of rows to scans + example: 10 + reverse: + type: boolean + description: direction of search + example: false + responses: + "201": + description: OK + content: + application/json: + schema: + type: object + properties: + rows: + type: array + items: + type: string + +component: + schema: + Error: + type: object + properties: + code: + type: integer + description: http return code + example: 400 + message: + type: string + description: summary of error + example: Invalid Request + error: + type: object + description: details on the error + properties: + code: + type: integer + description: internal error code + example: 3200006 + name: + type: string + description: name of error + example: invalid_http_request + what: + type: string + description: prettier version of error name + example: invalid http request + details: + type: array + description: list of additional information for debugging + items: + type: object + properties: + message: + type: string + description: debugging message + example: Unable to parse valid input from POST body + file: + type: string + description: file where error was thrown + example: http_plugin.hpp + line_number: + type: integer + description: line number in file where error was thrown + example: 246 + method: + type: string + description: function executed when error occured + example: parse_params + OK: + type: object + properties: + result: + type: string + description: status + example: ok + Runtime_Options: + type: object + properties: + max_transaction_time: + type: integer + description: Max transaction time + example: 100 + max_irreversible_block_age: + type: integer + description: Max irreversible block age + example: -1 + produce_time_offset_us: + type: integer + description: Time offset + example: -100000 + last_block_time_offset_us: + type: integer + description: Last block time offset + example: -200000 + max_scheduled_transaction_time_per_block_ms: + type: integer + description: Max scheduled transaction time per block in ms + example: 100 + incoming_defer_ratio: + type: string + description: Incoming defer ration, parsed to double + example: "1.00000000000000000" + greylist_limit: + type: integer + description: limit on number of Names supported by greylist + example: 1000