From 5171c645eb27ea9828a7bf14cd634d6314f55a6c Mon Sep 17 00:00:00 2001 From: Stephen <62410139+Bobinstein@users.noreply.github.com> Date: Wed, 23 Aug 2023 19:49:09 -0400 Subject: [PATCH 1/6] docs: Open-API docs for Admin Endpoints Added Admin enpoint docs into the Open-API configuration --- docs/openapi.yaml | 87 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) diff --git a/docs/openapi.yaml b/docs/openapi.yaml index a7481e91..fccc2797 100644 --- a/docs/openapi.yaml +++ b/docs/openapi.yaml @@ -48,7 +48,16 @@ tags: - name: Index Querying description: | Get data from the AR.IO Gateway index using GQL + - name: Admin + description: | + Access several password protected features and functions specific to your AR.IO Gateway.\nInput your ADMIN_API_KEY using the green "Authorize" button at the top of this page, or by clicking on the "lock" icon next to any password protected endpoint. components: + securitySchemes: + bearerAuth: + type: http + scheme: bearer + bearerFormat: userPassword + description: ADMIN_API_KEY set in your .env file. schemas: Block: type: object @@ -642,3 +651,81 @@ paths: # Index # "/graphql" + + # Admin + '/ar-io/admin/debug': + get: + tags: [Admin] + summary: Admin debugging information. + description: Get detailed information about the current operational state of your AR.IO Gateway, including information about any current warnings or errors. + operationId: adminDebug + responses: + '200': + description: Successful operation. + '401': + description: Unauthorized, API key likely incorrect. + security: + - bearerAuth: [] + '/ar-io/admin/queue-tx': + post: + tags: [Admin] + summary: Prioritize a transaction in the queue. + description: Stage a specific TX ID as priority for your Gateway to locate and index. + operationId: adminQueueTx + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + id: + type: string + pattern: '^[0-9a-zA-Z_-]{43}$' + description: TX ID of the transaction you would like to prioritize. + examples: + example1: + value: + id: '3lyxgbgEvqNSvJrTX2J7CfRychUD5KClFhhVLyTPNCQ' + responses: + '200': + description: Successful operation + '401': + description: Unauthorized, API key likely incorrect. + security: + - bearerAuth: [] + '/ar-io/admin/block-data': + put: + tags: [Admin] + summary: Blocks transactions or data-items so your AR.IO Gateway will not serve them. + description: Submits a TX ID or data-item hash for content you do not want your AR.IO Gateway to serve. Once submitted, your Gateway will not respond to requests for these transactions or data-items.\nWARNING - Testing a TX ID here WILL result in that data being blocked by your Gateway. + operationId: adminBlockData + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + id: + type: string + description: TX ID for a transaction you want to block. + notes: + type: string + description: Any notes or comments related to the block data. Documentation purposes only. + source: + type: string + description: The source from which the block data was obtained. Documentation purposes only. + examples: + example1: + value: + id: '3lyxgbgEvqNSvJrTX2J7CfRychUD5KClFhhVLyTPNCQ' + notes: 'This content is offensive' + source: 'Public Block list' + responses: + '200': + description: Successful operation. + '401': + description: Unauthorized, API key likely incorrect. + security: + - bearerAuth: [] From e95c68ac7be0a8c500b877b1760a742ba0002ec1 Mon Sep 17 00:00:00 2001 From: Stephen <62410139+Bobinstein@users.noreply.github.com> Date: Wed, 23 Aug 2023 21:21:45 -0400 Subject: [PATCH 2/6] docs: Expanded open-api docs for endpoints. Added summarys and descriptions to all endpoints currently covered in Open-api docs. --- docs/openapi.yaml | 80 ++++++++++++++++++++++++++++++++++++----------- 1 file changed, 62 insertions(+), 18 deletions(-) diff --git a/docs/openapi.yaml b/docs/openapi.yaml index fccc2797..99a0d1d7 100644 --- a/docs/openapi.yaml +++ b/docs/openapi.yaml @@ -50,7 +50,10 @@ tags: Get data from the AR.IO Gateway index using GQL - name: Admin description: | - Access several password protected features and functions specific to your AR.IO Gateway.\nInput your ADMIN_API_KEY using the green "Authorize" button at the top of this page, or by clicking on the "lock" icon next to any password protected endpoint. + Access several password protected features and functions specific to your AR.IO Gateway. + + + Input your ADMIN_API_KEY using the green "Authorize" button at the top of this page, or by clicking on the "lock" icon next to any password protected endpoint. components: securitySchemes: bearerAuth: @@ -351,10 +354,12 @@ paths: '/': get: tags: [Network] + summary: Network and Gateway Status. + description: Get information about the current status of the Network and your Gateway. responses: '200': description: |- - 200 response + Successful operation. content: application/json: schema: @@ -362,10 +367,12 @@ paths: '/info': get: tags: [Network] + summary: Network and Gateway Status, alternate endpoint. + description: An alternative option for accessing network and Gateway status. responses: '200': description: |- - 200 response + Successful operation. content: application/json: schema: @@ -373,10 +380,12 @@ paths: '/peers': get: tags: [Network] + summary: Get active peer list. + description: Gets a list of ip addresses for peers your Gateway is currently connected with. responses: '200': description: |- - 200 response + Successful operation. content: application/json: schema: @@ -384,6 +393,8 @@ paths: '/height': get: tags: [Network] + summary: Get current block height. + description: Gets the current block height of the Arweave network. responses: '200': description: |- @@ -404,6 +415,8 @@ paths: '/price/{size}': get: tags: [Pricing] + summary: Get price to store an amount of data. + description: Get the price, in Winston, required to store a specified amount of data, in bytes, on the Arweave network. parameters: - name: size in: path @@ -414,7 +427,7 @@ paths: responses: '200': description: |- - 200 response + Successful operation. content: # TODO text/plain ? text/html: @@ -423,6 +436,9 @@ paths: '/price/{size}/target': get: tags: [Pricing] + summary: Get price to transfer AR into a wallet and store an amount of data + description: | + Get the price, in Winston, required to transfer AR into a wallet and store a specified amount of data, in bytes, on the Arweave network. parameters: - name: size in: path @@ -433,7 +449,7 @@ paths: responses: '200': description: |- - 200 response + Successful operation. content: text/html: schema: @@ -443,6 +459,8 @@ paths: '/wallet/{address}/balance': get: tags: [Wallets] + summary: Get the current balance of a wallet. + description: Get the current balance of AR, in Winston, of a specified wallet address. parameters: - name: address in: path @@ -453,7 +471,7 @@ paths: responses: '200': description: |- - 200 response + Successful operation. content: # TODO text/plain ? text/html: @@ -462,6 +480,8 @@ paths: '/wallet/{address}/last_tx': get: tags: [Wallets] + summary: Get the last transaction of a wallet. + description: Get the TX ID from the most recent transaction a specified wallet completed. parameters: - name: address in: path @@ -472,7 +492,7 @@ paths: responses: '200': description: |- - 200 response + Successful operation. content: # TODO text/plain ? text/html: @@ -484,10 +504,12 @@ paths: '/current_block': get: tags: [Blocks] + summary: Get information about the current block. + description: Get detailed information about the current block on the Arweave network. responses: '200': description: |- - 200 response + Successful operation. content: application/json: schema: @@ -495,6 +517,8 @@ paths: '/block/height/{height}': get: tags: [Blocks] + summary: Get current block height. + description: Gets the current block height of the Arweave network. parameters: - name: height in: path @@ -505,7 +529,7 @@ paths: responses: '200': description: |- - 200 response + Successful operation. content: application/json: schema: @@ -513,6 +537,8 @@ paths: '/block/hash/{hash}': get: tags: [Blocks] + summary: Get block by hash. + description: Get block information based on a block's hash. parameters: - name: hash in: path @@ -523,7 +549,7 @@ paths: responses: '200': description: |- - 200 response + Successful operation. content: application/json: schema: @@ -531,10 +557,12 @@ paths: '/block/current': get: tags: [Blocks] + summary: Alternative endpoint to get current block. + description: Alternative endpoint to `/current_block`, gets current block information. responses: '200': description: |- - 200 response + Successful operation. content: application/json: schema: @@ -545,10 +573,12 @@ paths: '/tx/pending': get: tags: [Transactions] + summary: Get pending transactions. + description: Get list of transactions that are currently pending. responses: '200': description: |- - 200 response + Successful operation. content: application/json: schema: @@ -556,6 +586,8 @@ paths: '/tx/{txId}': get: tags: [Transactions] + summary: Get information about a transaction. + description: Get detailed information about a specific transaction. parameters: - name: txId in: path @@ -566,7 +598,7 @@ paths: responses: '200': description: |- - 200 response + Successful operation. content: application/json: schema: @@ -574,6 +606,8 @@ paths: '/tx/{txId}/offset': get: tags: [Transactions] + summary: Get transaction offset information. + description: Get information about the size and offset of a specified transaction. parameters: - name: txId in: path @@ -584,7 +618,7 @@ paths: responses: '200': description: |- - 200 response + Successful operation. content: application/json: schema: @@ -592,6 +626,8 @@ paths: '/tx/{txId}/status': get: tags: [Transactions] + summary: Get transaction status. + description: Get the status of a specified transaction. parameters: - name: txId in: path @@ -602,7 +638,7 @@ paths: responses: '200': description: |- - 200 response + Successful operation. content: application/json: schema: @@ -614,6 +650,8 @@ paths: '/{txId}': get: tags: [Cache] + summary: Get transaction. + description: Get the content of a specified transaction. parameters: - name: txId in: path @@ -624,7 +662,7 @@ paths: responses: '200': description: |- - 200 response + Successful operation. content: application/json: schema: @@ -634,6 +672,8 @@ paths: '/chunk/{offset}': get: tags: [Chunks] + summary: Get chunk offset information. + description: parameters: - name: offset in: path @@ -698,7 +738,11 @@ paths: put: tags: [Admin] summary: Blocks transactions or data-items so your AR.IO Gateway will not serve them. - description: Submits a TX ID or data-item hash for content you do not want your AR.IO Gateway to serve. Once submitted, your Gateway will not respond to requests for these transactions or data-items.\nWARNING - Testing a TX ID here WILL result in that data being blocked by your Gateway. + description: | + Submits a TX ID or data-item hash for content you do not want your AR.IO Gateway to serve. Once submitted, your Gateway will not respond to requests for these transactions or data-items. + + + WARNING - Testing a TX ID here WILL result in that data being blocked by your Gateway. operationId: adminBlockData requestBody: required: true From 0bae9e2feb59dba735994eaaa9f6c85d8c18979a Mon Sep 17 00:00:00 2001 From: Stephen <62410139+Bobinstein@users.noreply.github.com> Date: Wed, 23 Aug 2023 21:24:47 -0400 Subject: [PATCH 3/6] chore: modified .gitattributes added install-ytt.sh to gitattributes, added universal line to catch all .sh files and ensure proper line endings when cloned to windows machines. --- .gitattributes | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.gitattributes b/.gitattributes index 956b1799..05f5f0ac 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,2 +1,4 @@ /docker-entrypoint.sh text eol=lf /envoy/docker-entrypoint.sh text eol=lf +/envoy/install-ytt.sh text eol=lf +**/*.sh text eol=lf \ No newline at end of file From 51251739e786e6e502bdcafca67129ac899895ee Mon Sep 17 00:00:00 2001 From: Stephen <62410139+Bobinstein@users.noreply.github.com> Date: Thu, 24 Aug 2023 20:09:30 -0400 Subject: [PATCH 4/6] docs: updated docs with requested changes. --- docs/openapi.yaml | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/openapi.yaml b/docs/openapi.yaml index 99a0d1d7..84962d6b 100644 --- a/docs/openapi.yaml +++ b/docs/openapi.yaml @@ -51,15 +51,12 @@ tags: - name: Admin description: | Access several password protected features and functions specific to your AR.IO Gateway. - - - Input your ADMIN_API_KEY using the green "Authorize" button at the top of this page, or by clicking on the "lock" icon next to any password protected endpoint. components: securitySchemes: bearerAuth: type: http scheme: bearer - bearerFormat: userPassword + bearerFormat: apiToken description: ADMIN_API_KEY set in your .env file. schemas: Block: @@ -739,7 +736,7 @@ paths: tags: [Admin] summary: Blocks transactions or data-items so your AR.IO Gateway will not serve them. description: | - Submits a TX ID or data-item hash for content you do not want your AR.IO Gateway to serve. Once submitted, your Gateway will not respond to requests for these transactions or data-items. + Submits a TX ID/data-item ID or sha-256 content hash for content you do not want your AR.IO Gateway to serve. Once submitted, your Gateway will not respond to requests for these transactions or data-items. WARNING - Testing a TX ID here WILL result in that data being blocked by your Gateway. From 530a95afeb260811134660a17a7d25e39002a41a Mon Sep 17 00:00:00 2001 From: Stephen <62410139+Bobinstein@users.noreply.github.com> Date: Thu, 31 Aug 2023 13:56:49 -0400 Subject: [PATCH 5/6] docs: update for queue-tx endpoint --- docs/openapi.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/openapi.yaml b/docs/openapi.yaml index 84962d6b..e89a3e28 100644 --- a/docs/openapi.yaml +++ b/docs/openapi.yaml @@ -706,8 +706,8 @@ paths: '/ar-io/admin/queue-tx': post: tags: [Admin] - summary: Prioritize a transaction in the queue. - description: Stage a specific TX ID as priority for your Gateway to locate and index. + summary: Prioritize a transaction or bundle in the queue. + description: Stage a specific TX ID as priority for your Gateway to locate and index. This can be any L1 transaction, or bundle if your Gateway is configured to unbundle and index. operationId: adminQueueTx requestBody: required: true @@ -719,7 +719,7 @@ paths: id: type: string pattern: '^[0-9a-zA-Z_-]{43}$' - description: TX ID of the transaction you would like to prioritize. + description: TX ID of the transaction or bundle you would like to prioritize. examples: example1: value: From 689ec44f31635be8a881105057298b646353f4a7 Mon Sep 17 00:00:00 2001 From: Stephen <62410139+Bobinstein@users.noreply.github.com> Date: Thu, 31 Aug 2023 15:57:06 -0400 Subject: [PATCH 6/6] docs: corrected phrasing of queue-tx endpoint --- docs/openapi.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/openapi.yaml b/docs/openapi.yaml index e89a3e28..307ba5ee 100644 --- a/docs/openapi.yaml +++ b/docs/openapi.yaml @@ -707,7 +707,7 @@ paths: post: tags: [Admin] summary: Prioritize a transaction or bundle in the queue. - description: Stage a specific TX ID as priority for your Gateway to locate and index. This can be any L1 transaction, or bundle if your Gateway is configured to unbundle and index. + description: Stage a specific TX ID as priority for your Gateway to locate and index. This will trigger and queue bundle processing if the transaction is a bundle, and your Gateway is configured to unbundle and index. operationId: adminQueueTx requestBody: required: true @@ -719,7 +719,7 @@ paths: id: type: string pattern: '^[0-9a-zA-Z_-]{43}$' - description: TX ID of the transaction or bundle you would like to prioritize. + description: TX ID of the transaction you would like to prioritize. examples: example1: value: