From 6393c079952cc94e0d20e570b7090c6de66d6259 Mon Sep 17 00:00:00 2001 From: Eric Passmore Date: Fri, 23 Sep 2022 08:04:29 -0700 Subject: [PATCH 1/4] Updated docs for openapi /v1/trace_api - updated description with notes on options needed at startup - updated json returns for 400,404, and 500 - added get_transaction_trace method --- .../trace_api_plugin/trace_api.swagger.yaml | 177 +++++++++++++++++- 1 file changed, 175 insertions(+), 2 deletions(-) diff --git a/plugins/trace_api_plugin/trace_api.swagger.yaml b/plugins/trace_api_plugin/trace_api.swagger.yaml index c1ad3694c5..19f549533a 100644 --- a/plugins/trace_api_plugin/trace_api.swagger.yaml +++ b/plugins/trace_api_plugin/trace_api.swagger.yaml @@ -6,7 +6,7 @@ info: name: MIT url: https://opensource.org/licenses/MIT contact: - url: https://eos.io + url: https://eosnetwork.com servers: - url: '{protocol}://{host}:{port}/v1/' variables: @@ -24,7 +24,7 @@ components: paths: /trace_api/get_block: post: - description: Returns a block trace object containing retired actions and related metadata. + description: Returns a block trace object containing retired actions and related metadata. Must specifiy one option `trace-rpc-abi` or `no-trace-abis`. These options are provided at nodeos startup on the command line or in config.ini file. Configuration option `trace-rpc-abi` There must be at least one ABI specified OR the flag trace-no-abis must be used. ABIs are specified as "Key=Value" pairs in the form = Where can be an absolute path to a file containing a valid JSON-encoded ABI a relative path from `data-dir` to a file containing a valid JSON-encoded ABI. Configuration option `trace-no-abis` use to indicate that the RPC responses will not use ABIs operationId: get_block requestBody: content: @@ -48,7 +48,180 @@ paths: - $ref: "https://docs.eosnetwork.com/openapi/v2.0/BlockTraceV1.yaml" "400": description: Error - requested block number is invalid (not a number, larger than max int) + content: + application/json: + schema: + type: object + properties: + code: + type: integer + example: 400 + message: + type: string + example: "bad or missing block_num" + error: + type: object + properties: + code: + type: integer + example: 0 + name: + type: string + what: + type: string + details: + type: array + items: + type: string "404": description: Error - requested data not present on node + content: + application/json: + schema: + type: object + properties: + code: + type: integer + example: 400 + message: + type: string + example: "bad or missing block_num" + error: + type: object + properties: + code: + type: integer + example: 0 + name: + type: string + what: + type: string + details: + type: array + items: + type: string "500": description: Error - exceptional condition while processing get_block; e.g. corrupt files + content: + application/json: + schema: + type: object + properties: + code: + type: integer + example: 500 + message: + type: string + example: "Trace API encountered an Error which it cannot recover from. Please resolve the error and relaunch the process" + error: + type: object + properties: + code: + type: integer + example: 0 + name: + type: string + what: + type: string + details: + type: array + items: + type: string + + /trace_api/get_transaction_trace: + post: + description: foo + optionationId: get_transaction_trace + requestBody: + content: + application/json: + schema: + type: object + required: + - id + properties: + id: + type: integer + description: Proviade a transaction id + responses: + "200": + description: ok + "400": + content: + application/json: + schema: + type: object + properties: + code: + type: integer + example: 400 + message: + type: string + example: "bad or missing block_num" + error: + type: object + properties: + code: + type: integer + example: 0 + name: + type: string + what: + type: string + details: + type: array + items: + type: string + "404": + content: + application/json: + schema: + type: object + properties: + code: + type: integer + example: 400 + message: + type: string + example: "bad or missing block_num" + error: + type: object + properties: + code: + type: integer + example: 0 + name: + type: string + what: + type: string + details: + type: array + items: + type: string + "500": + description: Error - exceptional condition while processing get_block; e.g. corrupt files + content: + application/json: + schema: + type: object + properties: + code: + type: integer + example: 500 + message: + type: string + example: "Trace API encountered an Error which it cannot recover from. Please resolve the error and relaunch the process" + error: + type: object + properties: + code: + type: integer + example: 0 + name: + type: string + what: + type: string + details: + type: array + items: + type: string From 8827ce38a4c777925cfe44116a2a35fa2ff83dd0 Mon Sep 17 00:00:00 2001 From: Eric Passmore Date: Fri, 23 Sep 2022 08:24:57 -0700 Subject: [PATCH 2/4] updated trace_api openapi docs - updated return schema for get_block - updated description for get_transaction_trace --- .../trace_api_plugin/trace_api.swagger.yaml | 25 +++++++++++++++---- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/plugins/trace_api_plugin/trace_api.swagger.yaml b/plugins/trace_api_plugin/trace_api.swagger.yaml index 19f549533a..0bd3b97e43 100644 --- a/plugins/trace_api_plugin/trace_api.swagger.yaml +++ b/plugins/trace_api_plugin/trace_api.swagger.yaml @@ -43,9 +43,22 @@ paths: content: application/json: schema: - oneOf: - - $ref: "https://docs.eosnetwork.com/openapi/v2.0/BlockTraceV0.yaml" - - $ref: "https://docs.eosnetwork.com/openapi/v2.0/BlockTraceV1.yaml" + type: object + properties: + id: + type: string + number: + type: integer + previous_id: + type: string + status: + type: string + enum: ["irreversible", "pending"] + example: pending + timestamp: + type: string + producer: + type: string "400": description: Error - requested block number is invalid (not a number, larger than max int) content: @@ -130,7 +143,7 @@ paths: /trace_api/get_transaction_trace: post: - description: foo + description: Does a scan of the trace files looking for the transaction optionationId: get_transaction_trace requestBody: content: @@ -145,7 +158,9 @@ paths: description: Proviade a transaction id responses: "200": - description: ok + content: + application/json: + schema: "400": content: application/json: From fa87b159edb77dee82d08bde0ffd9d58e0177ed4 Mon Sep 17 00:00:00 2001 From: Eric Passmore Date: Fri, 23 Sep 2022 12:24:40 -0700 Subject: [PATCH 3/4] updated schema for trace_api openapi - Added new component schemas - ERROR_DETAILS - TRACE - TRANSACTION_HEADER - TRANSACTION_TRACE - BLOCK_TRACE - updated 4xx errors with shared ERROR_DETAILS component - verification and updates for schema returned for get_block - verifcation and updates for schema returned for get_transaction --- .../trace_api_plugin/trace_api.swagger.yaml | 282 ++++++++++++------ 1 file changed, 187 insertions(+), 95 deletions(-) diff --git a/plugins/trace_api_plugin/trace_api.swagger.yaml b/plugins/trace_api_plugin/trace_api.swagger.yaml index 0bd3b97e43..1531dae149 100644 --- a/plugins/trace_api_plugin/trace_api.swagger.yaml +++ b/plugins/trace_api_plugin/trace_api.swagger.yaml @@ -1,6 +1,7 @@ openapi: 3.0.0 info: title: Trace API + description: This plubing must specifiy one option `trace-rpc-abi` or `no-trace-abis`. These options are provided at nodeos startup on the command line or in config.ini file. Configuration option `trace-rpc-abi` There must be at least one ABI specified OR the flag trace-no-abis must be used. ABIs are specified as "Key=Value" pairs in the form = Where can be an absolute path to a file containing a valid JSON-encoded ABI a relative path from `data-dir` to a file containing a valid JSON-encoded ABI. Configuration option `trace-no-abis` use to indicate that the RPC responses version: 1.0.0 license: name: MIT @@ -21,10 +22,13 @@ servers: default: "8080" components: schemas: {} +security: + - {} paths: /trace_api/get_block: post: - description: Returns a block trace object containing retired actions and related metadata. Must specifiy one option `trace-rpc-abi` or `no-trace-abis`. These options are provided at nodeos startup on the command line or in config.ini file. Configuration option `trace-rpc-abi` There must be at least one ABI specified OR the flag trace-no-abis must be used. ABIs are specified as "Key=Value" pairs in the form = Where can be an absolute path to a file containing a valid JSON-encoded ABI a relative path from `data-dir` to a file containing a valid JSON-encoded ABI. Configuration option `trace-no-abis` use to indicate that the RPC responses will not use ABIs + summary: get block + description: Returns a block trace object containing retired actions and related metadata. operationId: get_block requestBody: content: @@ -43,22 +47,7 @@ paths: content: application/json: schema: - type: object - properties: - id: - type: string - number: - type: integer - previous_id: - type: string - status: - type: string - enum: ["irreversible", "pending"] - example: pending - timestamp: - type: string - producer: - type: string + $ref: "#/component/schema/BLOCK_TRACE" "400": description: Error - requested block number is invalid (not a number, larger than max int) content: @@ -73,19 +62,7 @@ paths: type: string example: "bad or missing block_num" error: - type: object - properties: - code: - type: integer - example: 0 - name: - type: string - what: - type: string - details: - type: array - items: - type: string + $ref: "#/component/schema/ERROR_DETAILS" "404": description: Error - requested data not present on node content: @@ -100,19 +77,7 @@ paths: type: string example: "bad or missing block_num" error: - type: object - properties: - code: - type: integer - example: 0 - name: - type: string - what: - type: string - details: - type: array - items: - type: string + $ref: "#/component/schema/ERROR_DETAILS" "500": description: Error - exceptional condition while processing get_block; e.g. corrupt files content: @@ -127,22 +92,11 @@ paths: type: string example: "Trace API encountered an Error which it cannot recover from. Please resolve the error and relaunch the process" error: - type: object - properties: - code: - type: integer - example: 0 - name: - type: string - what: - type: string - details: - type: array - items: - type: string + $ref: "#/component/schema/ERROR_DETAILS" /trace_api/get_transaction_trace: post: + summary: transaction trace description: Does a scan of the trace files looking for the transaction optionationId: get_transaction_trace requestBody: @@ -161,7 +115,9 @@ paths: content: application/json: schema: + $ref: "#/component/schema/TRANSACTION_TRACE" "400": + description: Error - requested block number is invalid (not a number, larger than max int) content: application/json: schema: @@ -174,20 +130,9 @@ paths: type: string example: "bad or missing block_num" error: - type: object - properties: - code: - type: integer - example: 0 - name: - type: string - what: - type: string - details: - type: array - items: - type: string + $ref: "#/component/schema/ERROR_DETAILS" "404": + description: Error - requested data not present on node content: application/json: schema: @@ -200,19 +145,7 @@ paths: type: string example: "bad or missing block_num" error: - type: object - properties: - code: - type: integer - example: 0 - name: - type: string - what: - type: string - details: - type: array - items: - type: string + $ref: "#/component/schema/ERROR_DETAILS" "500": description: Error - exceptional condition while processing get_block; e.g. corrupt files content: @@ -227,16 +160,175 @@ paths: type: string example: "Trace API encountered an Error which it cannot recover from. Please resolve the error and relaunch the process" error: - type: object - properties: - code: - type: integer - example: 0 - name: - type: string - what: - type: string - details: - type: array - items: - type: string + $ref: "#/component/schema/ERROR_DETAILS" +component: + schema: + TRACE: + type: object + properties: + global_squence: + type: integer + example: 669 + receiver: + type: string + example: myproducer + account: + type: string + example: esio.token + action: + type: string + example: transfer + authorization: + type: array + items: + type: object + properties: + account: + type: string + example: myaccount + permission: + type: string + example: active + data: + type: string + $ref: "https://docs.eosnetwork.com/openapi/v2.0/Sha256.yaml" + return_value: + type: string + example: "" + params: + type: object + properties: + from: + type: string + example: eosio + to: + type: string + example: myproducer + quantity: + type: string + example: "10.000 SYS" + memo: + type: string + example: "first transfer" + TRANSACTION_HEADER: + type: object + properties: + expiration: + type: string + example: "2019-06-18T00:00:00" + ref_block_num: + type: integer + example: 25 + ref_block_prefix: + type: integer + example: 61809694 + max_net_usage_words: + type: integer + example: 0 + max_cpu_usage_ms: + type: integer + example: 0 + delay_sec: + type: integer + example: 0 + TRANSACTION_TRACE: + type: object + properties: + id: + type: string + $ref: "https://docs.eosnetwork.com/openapi/v2.0/Sha256.yaml" + block_num: + type: integer + example: 31 + block_time: + type: string + example: "2019-06-18T00:00:00" + producer_block_id: + type: string + $ref: "https://docs.eosnetwork.com/openapi/v2.0/Sha256.yaml" + actions: + type: array + items: + $ref: "#/component/schema/TRACE" + status: + type: string + example: executed + cpu_usage_us: + type: integer + example: 669 + net_usage_words: + type: integer + example: 6 + signatures: + type: array + items: + $ref: "https://docs.eosnetwork.com/openapi/v2.0/CppSignature.yaml" + transaction_header: + type: object + $ref: "#/component/schema/TRANSACTION_HEADER" + BLOCK_TRACE: + type: object + properties: + id: + $ref: "https://docs.eosnetwork.com/openapi/v2.0/Sha256.yaml" + number: + type: integer + example: 31 + previous_id: + $ref: "https://docs.eosnetwork.com/openapi/v2.0/Sha256.yaml" + status: + type: string + enum: + - "irreversible" + - "executed" + - "pending" + example: executed + timestamp: + type: string + example: "2019-06-18T00:00:00" + producer: + type: string + example: myproducer + transaction_mroot: + $ref: "https://docs.eosnetwork.com/openapi/v2.0/Sha256.yaml" + action_mroot: + $ref: "https://docs.eosnetwork.com/openapi/v2.0/Sha256.yaml" + schedule_version: + type: integer + example: 1 + transactions: + type: array + items: + type: object + properties: + id: + $ref: "https://docs.eosnetwork.com/openapi/v2.0/Sha256.yaml" + block_num: + type: integer + example: 31 + block_time: + type: string + example: "2019-06-18T00:00:00" + producer_block_id: + $ref: "https://docs.eosnetwork.com/openapi/v2.0/Sha256.yaml" + actions: + type: array + items: + $ref: "#/component/schema/TRACE" + transaction_header: + type: object + $ref: "#/component/schema/TRANSACTION_HEADER" + ERROR_DETAILS: + type: object + properties: + code: + type: integer + example: 0 + name: + type: string + what: + type: string + details: + type: array + items: + type: string From dfbc9cda6dd5ca8a714f5e3da1f320d04d9de13c Mon Sep 17 00:00:00 2001 From: Eric Passmore Date: Mon, 26 Sep 2022 15:44:35 -0700 Subject: [PATCH 4/4] trace_api docs show all schemas returned - shorted description refered back to developer docs - allow return types for get_blocks any of BlockTraceV0, BlockTraceV1, BlockTraceV2 - BlockTraceV2 can return either Transaction Type V1 or Transaction Type V2 - allow return types for get_transaction_trace any of TransactionTraceV0, TransactionTraceV1, TransactionTraceV2 --- .../trace_api_plugin/trace_api.swagger.yaml | 121 ++---------------- 1 file changed, 10 insertions(+), 111 deletions(-) diff --git a/plugins/trace_api_plugin/trace_api.swagger.yaml b/plugins/trace_api_plugin/trace_api.swagger.yaml index 1531dae149..46bb143496 100644 --- a/plugins/trace_api_plugin/trace_api.swagger.yaml +++ b/plugins/trace_api_plugin/trace_api.swagger.yaml @@ -1,7 +1,7 @@ openapi: 3.0.0 info: title: Trace API - description: This plubing must specifiy one option `trace-rpc-abi` or `no-trace-abis`. These options are provided at nodeos startup on the command line or in config.ini file. Configuration option `trace-rpc-abi` There must be at least one ABI specified OR the flag trace-no-abis must be used. ABIs are specified as "Key=Value" pairs in the form = Where can be an absolute path to a file containing a valid JSON-encoded ABI a relative path from `data-dir` to a file containing a valid JSON-encoded ABI. Configuration option `trace-no-abis` use to indicate that the RPC responses + description: See developer documentation at https://docs.eosnetwork.com for information on enabling this plugin. version: 1.0.0 license: name: MIT @@ -47,7 +47,10 @@ paths: content: application/json: schema: - $ref: "#/component/schema/BLOCK_TRACE" + oneOf: + - $ref: "https://docs.eosnetwork.com/openapi/v2.0/BlockTraceV0.yaml" + - $ref: "https://docs.eosnetwork.com/openapi/v2.0/BlockTraceV1.yaml" + - $ref: "https://docs.eosnetwork.com/openapi/v2.0/BlockTraceV2.yaml" "400": description: Error - requested block number is invalid (not a number, larger than max int) content: @@ -115,7 +118,11 @@ paths: content: application/json: schema: - $ref: "#/component/schema/TRANSACTION_TRACE" + oneOf: + - $ref: "https://docs.eosnetwork.com/openapi/v2.0/TransactionTraceV0.yaml" + - $ref: "https://docs.eosnetwork.com/openapi/v2.0/TransactionTraceV1.yaml" + - $ref: "https://docs.eosnetwork.com/openapi/v2.0/TransactionTraceV2.yaml" + - $ref: "https://docs.eosnetwork.com/openapi/v2.0/TransactionTraceV3.yaml" "400": description: Error - requested block number is invalid (not a number, larger than max int) content: @@ -210,114 +217,6 @@ component: memo: type: string example: "first transfer" - TRANSACTION_HEADER: - type: object - properties: - expiration: - type: string - example: "2019-06-18T00:00:00" - ref_block_num: - type: integer - example: 25 - ref_block_prefix: - type: integer - example: 61809694 - max_net_usage_words: - type: integer - example: 0 - max_cpu_usage_ms: - type: integer - example: 0 - delay_sec: - type: integer - example: 0 - TRANSACTION_TRACE: - type: object - properties: - id: - type: string - $ref: "https://docs.eosnetwork.com/openapi/v2.0/Sha256.yaml" - block_num: - type: integer - example: 31 - block_time: - type: string - example: "2019-06-18T00:00:00" - producer_block_id: - type: string - $ref: "https://docs.eosnetwork.com/openapi/v2.0/Sha256.yaml" - actions: - type: array - items: - $ref: "#/component/schema/TRACE" - status: - type: string - example: executed - cpu_usage_us: - type: integer - example: 669 - net_usage_words: - type: integer - example: 6 - signatures: - type: array - items: - $ref: "https://docs.eosnetwork.com/openapi/v2.0/CppSignature.yaml" - transaction_header: - type: object - $ref: "#/component/schema/TRANSACTION_HEADER" - BLOCK_TRACE: - type: object - properties: - id: - $ref: "https://docs.eosnetwork.com/openapi/v2.0/Sha256.yaml" - number: - type: integer - example: 31 - previous_id: - $ref: "https://docs.eosnetwork.com/openapi/v2.0/Sha256.yaml" - status: - type: string - enum: - - "irreversible" - - "executed" - - "pending" - example: executed - timestamp: - type: string - example: "2019-06-18T00:00:00" - producer: - type: string - example: myproducer - transaction_mroot: - $ref: "https://docs.eosnetwork.com/openapi/v2.0/Sha256.yaml" - action_mroot: - $ref: "https://docs.eosnetwork.com/openapi/v2.0/Sha256.yaml" - schedule_version: - type: integer - example: 1 - transactions: - type: array - items: - type: object - properties: - id: - $ref: "https://docs.eosnetwork.com/openapi/v2.0/Sha256.yaml" - block_num: - type: integer - example: 31 - block_time: - type: string - example: "2019-06-18T00:00:00" - producer_block_id: - $ref: "https://docs.eosnetwork.com/openapi/v2.0/Sha256.yaml" - actions: - type: array - items: - $ref: "#/component/schema/TRACE" - transaction_header: - type: object - $ref: "#/component/schema/TRANSACTION_HEADER" ERROR_DETAILS: type: object properties: