From 8f7d044b69a0ef7e1f1fc1916fd3e90a785e4d62 Mon Sep 17 00:00:00 2001 From: rdlrt <3169068+rdlrt@users.noreply.github.com> Date: Fri, 3 Nov 2023 13:44:45 +1100 Subject: [PATCH] Fix specs for ogmios providing an example alongwith list of methods supported --- specs/results/koiosapi-guild.yaml | 137 ++++++++++++++++++----- specs/results/koiosapi-mainnet.yaml | 137 ++++++++++++++++++----- specs/results/koiosapi-preprod.yaml | 137 ++++++++++++++++++----- specs/results/koiosapi-preview.yaml | 137 ++++++++++++++++++----- specs/templates/3-api-requestBodies.yaml | 37 ++++++ specs/templates/4-api-schemas.yaml | 26 +++++ specs/templates/api-main.yaml | 74 +++++++----- 7 files changed, 540 insertions(+), 145 deletions(-) diff --git a/specs/results/koiosapi-guild.yaml b/specs/results/koiosapi-guild.yaml index 1bfb461d..4a2302d5 100644 --- a/specs/results/koiosapi-guild.yaml +++ b/specs/results/koiosapi-guild.yaml @@ -1584,43 +1584,30 @@ paths: $ref: "#/components/responses/NotFound" summary: Datum Information description: List of datum information for given datum hashes - /ogmios/?EvaluateTransaction: #ogmios-api + /ogmios/: #ogmios-api post: tags: - Ogmios - x-code-samples: - - lang: "Shell" - source: | - # Assuming ${data} contains EvaluateTransaction payload as documented on Ogmios v6 site. - curl -X POST \ - --header "Content-Type: application/cbor" \ - --data-binary ${data} https://api.koios.rest/api/ogmios/?EvaluateTransaction + requestBody: + $ref: "#/components/requestBodies/ogmios" responses: "200": - description: OK + description: Current tip of the chain, identified by a slot and a block header hash. + content: + application/json: + schema: + $ref: "#/components/schemas/ogmiostip" "400": description: An error occured while submitting transaction. - summary: Evaluate Transaction - description: Evaluate execution units of scripts in a well-formed transaction. Please refer to Ogmios documentation [here](https://ogmios.dev/api/#operation-publish-/?EvaluateTransaction) for complete spec - /ogmios/?SubmitTransaction: #ogmios-api - post: - tags: - - Ogmios - x-code-samples: - - lang: "Shell" - source: | - # Assuming ${data} contains a CBOR-serialized signed transaction (base16-encoded) as documented on Ogmios v6 site. - curl -X POST \ - --header "Content-Type: application/cbor" \ - --data-binary ${data} https://api.koios.rest/api/ogmios/?SubmitTransaction - responses: - "200": - description: OK - "400": - description: An error occured while querying transaction. - summary: Submit Transaction - description: Submit a signed and serialized transaction to the network. Please refer to Ogmios documentation [here](https://ogmios.dev/api/#operation-publish-/?SubmitTransaction) for complete spec + summary: Query Example + description: | + Query the current tip of the Network. +
+
+ We do support transparent forwarding for various methods from Ogmios, you can read about those here. +
+ components: parameters: select: @@ -2257,6 +2244,43 @@ components: - f82e568d42604fd71424d193c86ec00c97aead2b8f018e81c3139d9e3770c735#0 - 88ae22495123c7ee37a0bbe865243757185a302ed5359d1eae9347030628290a#0 _extended: false + ogmios: + content: + application/json: + schema: + required: + - jsonrpc + - method + type: object + properties: + jsonrpc: + format: text + type: string + description: Identifier for JSON-RPC 2.0 standard + example: "2.0" + method: + format: text + type: string + description: The Ogmios method to be called (see more details [here](#tag--Ogmios)) + enum: + - "queryNetwork/blockHeight" + - "queryNetwork/genesisConfiguration" + - "queryNetwork/startTime" + - "queryNetwork/tip" + - "queryLedgerState/epoch" + - "queryLedgerState/eraStart" + - "queryLedgerState/eraSummaries" + - "queryLedgerState/liveStakeDistribution" + - "queryLedgerState/protocolParameters" + - "queryLedgerState/proposedProtocolParameters" + - "queryLedgerState/stakePools" + - "submitTransaction" + - "evaluateTransaction" + example: "queryNetwork/tip" + params: + type: object + description: Any parameters relevant to the specific method to be called + nullable: true securitySchemes: bearerAuth: type: http @@ -2868,6 +2892,7 @@ components: nullable: true epoch_params: type: array + description: Epoch parameters (all fields nullable for pre-Shelley/Gougen epochs except first block hash) items: properties: epoch_no: @@ -4152,6 +4177,31 @@ components: $ref: "#/components/schemas/script_info/items/properties/value" bytes: $ref: "#/components/schemas/script_info/items/properties/bytes" + ogmiostip: + type: object + properties: + jsonrpc: + format: text + type: string + description: Identifier for JSON-RPC 2.0 standard + example: "2.0" + method: + format: text + type: string + description: The Ogmios method that was called in the request + example: "queryNetwork/tip" + result: + type: object + description: Result of the query + properties: + slot: + type: number + description: Absolute slot number on chain + example: 59886800 + id: + type: string + description: Block Hash (Blake2b 32-byte hash digest, encoded in base16) + example: "df5678c9774b7bc8c60a4c83b63c3676e618640ad05f7d1ee775b68939cf77d1" headers: {} responses: OK: @@ -4192,5 +4242,34 @@ tags: - name: Script description: Query information about specific scripts (Smart Contracts) x-tag-expanded: false + - name: Ogmios + description: | + Various stateless queries against Ogmios v6 instance. Please note that ogmios follows JSON-RPC 2.0 method, the example spec on koios.rest is *ONLY* for `queryNetwork/tip`, + but all the methods listed below are all accepted. Instead of duplicating specs, we would refer you directly to Ogmios documentation [here](https://ogmios.dev/api) for complete specs. + +
+
+ Note that for queries to be stateless across instances on the globe, we cannot acquire local state as successive calls will be across different instances. Also, we'd want to avoid getting an instance DDoS'd with large queries. + Thus, we will only expose the following methods from monitoring servers, instance providers can expose entire ogmios endpoints if desirable: +
+ + + ### Network + - [queryNetwork/blockHeight](https://ogmios.dev/api/#operation-publish-/?QueryNetworkBlockHeight) + - [queryNetwork/genesisConfiguration](https://ogmios.dev/api/#operation-publish-/?QueryNetworkGenesisConfiguration) + - [queryNetwork/startTime](https://ogmios.dev/api/#operation-publish-/?QueryNetworkStartTime) + - [queryNetwork/tip](https://ogmios.dev/api/#operation-publish-/?QueryNetworkTip) + ### Ledger-State + - [queryLedgerState/epoch](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateEpoch) + - [queryLedgerState/eraStart](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateEraStart) + - [queryLedgerState/eraSummaries](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateEraSummaries) + - [queryLedgerState/liveStakeDistribution](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateLiveStakeDistribution) + - [queryLedgerState/protocolParameters](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateProtocolParameters) + - [queryLedgerState/proposedProtocolParameters](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateProposedProtocolParameters) + - [queryLedgerState/stakePools](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateStakePools) + ### Transactions + - [submitTransaction](https://ogmios.dev/mini-protocols/local-tx-submission/#submitting-transactions) + - [evaluateTransaction](https://ogmios.dev/mini-protocols/local-tx-submission/#evaluating-transactions) + x-tag-expanded: true security: - bearerAuth: [] diff --git a/specs/results/koiosapi-mainnet.yaml b/specs/results/koiosapi-mainnet.yaml index f8005196..accd078e 100644 --- a/specs/results/koiosapi-mainnet.yaml +++ b/specs/results/koiosapi-mainnet.yaml @@ -1584,43 +1584,30 @@ paths: $ref: "#/components/responses/NotFound" summary: Datum Information description: List of datum information for given datum hashes - /ogmios/?EvaluateTransaction: #ogmios-api + /ogmios/: #ogmios-api post: tags: - Ogmios - x-code-samples: - - lang: "Shell" - source: | - # Assuming ${data} contains EvaluateTransaction payload as documented on Ogmios v6 site. - curl -X POST \ - --header "Content-Type: application/cbor" \ - --data-binary ${data} https://api.koios.rest/api/ogmios/?EvaluateTransaction + requestBody: + $ref: "#/components/requestBodies/ogmios" responses: "200": - description: OK + description: Current tip of the chain, identified by a slot and a block header hash. + content: + application/json: + schema: + $ref: "#/components/schemas/ogmiostip" "400": description: An error occured while submitting transaction. - summary: Evaluate Transaction - description: Evaluate execution units of scripts in a well-formed transaction. Please refer to Ogmios documentation [here](https://ogmios.dev/api/#operation-publish-/?EvaluateTransaction) for complete spec - /ogmios/?SubmitTransaction: #ogmios-api - post: - tags: - - Ogmios - x-code-samples: - - lang: "Shell" - source: | - # Assuming ${data} contains a CBOR-serialized signed transaction (base16-encoded) as documented on Ogmios v6 site. - curl -X POST \ - --header "Content-Type: application/cbor" \ - --data-binary ${data} https://api.koios.rest/api/ogmios/?SubmitTransaction - responses: - "200": - description: OK - "400": - description: An error occured while querying transaction. - summary: Submit Transaction - description: Submit a signed and serialized transaction to the network. Please refer to Ogmios documentation [here](https://ogmios.dev/api/#operation-publish-/?SubmitTransaction) for complete spec + summary: Query Example + description: | + Query the current tip of the Network. +
+
+ We do support transparent forwarding for various methods from Ogmios, you can read about those here. +
+ components: parameters: select: @@ -2257,6 +2244,43 @@ components: - f144a8264acf4bdfe2e1241170969c930d64ab6b0996a4a45237b623f1dd670e#0 - 0b8ba3bed976fa4913f19adc9f6dd9063138db5b4dd29cecde369456b5155e94#0 _extended: false + ogmios: + content: + application/json: + schema: + required: + - jsonrpc + - method + type: object + properties: + jsonrpc: + format: text + type: string + description: Identifier for JSON-RPC 2.0 standard + example: "2.0" + method: + format: text + type: string + description: The Ogmios method to be called (see more details [here](#tag--Ogmios)) + enum: + - "queryNetwork/blockHeight" + - "queryNetwork/genesisConfiguration" + - "queryNetwork/startTime" + - "queryNetwork/tip" + - "queryLedgerState/epoch" + - "queryLedgerState/eraStart" + - "queryLedgerState/eraSummaries" + - "queryLedgerState/liveStakeDistribution" + - "queryLedgerState/protocolParameters" + - "queryLedgerState/proposedProtocolParameters" + - "queryLedgerState/stakePools" + - "submitTransaction" + - "evaluateTransaction" + example: "queryNetwork/tip" + params: + type: object + description: Any parameters relevant to the specific method to be called + nullable: true securitySchemes: bearerAuth: type: http @@ -2868,6 +2892,7 @@ components: nullable: true epoch_params: type: array + description: Epoch parameters (all fields nullable for pre-Shelley/Gougen epochs except first block hash) items: properties: epoch_no: @@ -4152,6 +4177,31 @@ components: $ref: "#/components/schemas/script_info/items/properties/value" bytes: $ref: "#/components/schemas/script_info/items/properties/bytes" + ogmiostip: + type: object + properties: + jsonrpc: + format: text + type: string + description: Identifier for JSON-RPC 2.0 standard + example: "2.0" + method: + format: text + type: string + description: The Ogmios method that was called in the request + example: "queryNetwork/tip" + result: + type: object + description: Result of the query + properties: + slot: + type: number + description: Absolute slot number on chain + example: 59886800 + id: + type: string + description: Block Hash (Blake2b 32-byte hash digest, encoded in base16) + example: "df5678c9774b7bc8c60a4c83b63c3676e618640ad05f7d1ee775b68939cf77d1" headers: {} responses: OK: @@ -4192,5 +4242,34 @@ tags: - name: Script description: Query information about specific scripts (Smart Contracts) x-tag-expanded: false + - name: Ogmios + description: | + Various stateless queries against Ogmios v6 instance. Please note that ogmios follows JSON-RPC 2.0 method, the example spec on koios.rest is *ONLY* for `queryNetwork/tip`, + but all the methods listed below are all accepted. Instead of duplicating specs, we would refer you directly to Ogmios documentation [here](https://ogmios.dev/api) for complete specs. + +
+
+ Note that for queries to be stateless across instances on the globe, we cannot acquire local state as successive calls will be across different instances. Also, we'd want to avoid getting an instance DDoS'd with large queries. + Thus, we will only expose the following methods from monitoring servers, instance providers can expose entire ogmios endpoints if desirable: +
+ + + ### Network + - [queryNetwork/blockHeight](https://ogmios.dev/api/#operation-publish-/?QueryNetworkBlockHeight) + - [queryNetwork/genesisConfiguration](https://ogmios.dev/api/#operation-publish-/?QueryNetworkGenesisConfiguration) + - [queryNetwork/startTime](https://ogmios.dev/api/#operation-publish-/?QueryNetworkStartTime) + - [queryNetwork/tip](https://ogmios.dev/api/#operation-publish-/?QueryNetworkTip) + ### Ledger-State + - [queryLedgerState/epoch](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateEpoch) + - [queryLedgerState/eraStart](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateEraStart) + - [queryLedgerState/eraSummaries](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateEraSummaries) + - [queryLedgerState/liveStakeDistribution](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateLiveStakeDistribution) + - [queryLedgerState/protocolParameters](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateProtocolParameters) + - [queryLedgerState/proposedProtocolParameters](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateProposedProtocolParameters) + - [queryLedgerState/stakePools](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateStakePools) + ### Transactions + - [submitTransaction](https://ogmios.dev/mini-protocols/local-tx-submission/#submitting-transactions) + - [evaluateTransaction](https://ogmios.dev/mini-protocols/local-tx-submission/#evaluating-transactions) + x-tag-expanded: true security: - bearerAuth: [] diff --git a/specs/results/koiosapi-preprod.yaml b/specs/results/koiosapi-preprod.yaml index 222bbe72..b56208d5 100644 --- a/specs/results/koiosapi-preprod.yaml +++ b/specs/results/koiosapi-preprod.yaml @@ -1584,43 +1584,30 @@ paths: $ref: "#/components/responses/NotFound" summary: Datum Information description: List of datum information for given datum hashes - /ogmios/?EvaluateTransaction: #ogmios-api + /ogmios/: #ogmios-api post: tags: - Ogmios - x-code-samples: - - lang: "Shell" - source: | - # Assuming ${data} contains EvaluateTransaction payload as documented on Ogmios v6 site. - curl -X POST \ - --header "Content-Type: application/cbor" \ - --data-binary ${data} https://api.koios.rest/api/ogmios/?EvaluateTransaction + requestBody: + $ref: "#/components/requestBodies/ogmios" responses: "200": - description: OK + description: Current tip of the chain, identified by a slot and a block header hash. + content: + application/json: + schema: + $ref: "#/components/schemas/ogmiostip" "400": description: An error occured while submitting transaction. - summary: Evaluate Transaction - description: Evaluate execution units of scripts in a well-formed transaction. Please refer to Ogmios documentation [here](https://ogmios.dev/api/#operation-publish-/?EvaluateTransaction) for complete spec - /ogmios/?SubmitTransaction: #ogmios-api - post: - tags: - - Ogmios - x-code-samples: - - lang: "Shell" - source: | - # Assuming ${data} contains a CBOR-serialized signed transaction (base16-encoded) as documented on Ogmios v6 site. - curl -X POST \ - --header "Content-Type: application/cbor" \ - --data-binary ${data} https://api.koios.rest/api/ogmios/?SubmitTransaction - responses: - "200": - description: OK - "400": - description: An error occured while querying transaction. - summary: Submit Transaction - description: Submit a signed and serialized transaction to the network. Please refer to Ogmios documentation [here](https://ogmios.dev/api/#operation-publish-/?SubmitTransaction) for complete spec + summary: Query Example + description: | + Query the current tip of the Network. +
+
+ We do support transparent forwarding for various methods from Ogmios, you can read about those here. +
+ components: parameters: select: @@ -2257,6 +2244,43 @@ components: - d10133964da9e443b303917fd0b7644ae3d01c133deff85b4f59416c2d00f530#0 - 145688d3619e7524510ea64c0ec6363b77a9b8da179ef9bb0273a0940d57d576#0 _extended: false + ogmios: + content: + application/json: + schema: + required: + - jsonrpc + - method + type: object + properties: + jsonrpc: + format: text + type: string + description: Identifier for JSON-RPC 2.0 standard + example: "2.0" + method: + format: text + type: string + description: The Ogmios method to be called (see more details [here](#tag--Ogmios)) + enum: + - "queryNetwork/blockHeight" + - "queryNetwork/genesisConfiguration" + - "queryNetwork/startTime" + - "queryNetwork/tip" + - "queryLedgerState/epoch" + - "queryLedgerState/eraStart" + - "queryLedgerState/eraSummaries" + - "queryLedgerState/liveStakeDistribution" + - "queryLedgerState/protocolParameters" + - "queryLedgerState/proposedProtocolParameters" + - "queryLedgerState/stakePools" + - "submitTransaction" + - "evaluateTransaction" + example: "queryNetwork/tip" + params: + type: object + description: Any parameters relevant to the specific method to be called + nullable: true securitySchemes: bearerAuth: type: http @@ -2868,6 +2892,7 @@ components: nullable: true epoch_params: type: array + description: Epoch parameters (all fields nullable for pre-Shelley/Gougen epochs except first block hash) items: properties: epoch_no: @@ -4152,6 +4177,31 @@ components: $ref: "#/components/schemas/script_info/items/properties/value" bytes: $ref: "#/components/schemas/script_info/items/properties/bytes" + ogmiostip: + type: object + properties: + jsonrpc: + format: text + type: string + description: Identifier for JSON-RPC 2.0 standard + example: "2.0" + method: + format: text + type: string + description: The Ogmios method that was called in the request + example: "queryNetwork/tip" + result: + type: object + description: Result of the query + properties: + slot: + type: number + description: Absolute slot number on chain + example: 59886800 + id: + type: string + description: Block Hash (Blake2b 32-byte hash digest, encoded in base16) + example: "df5678c9774b7bc8c60a4c83b63c3676e618640ad05f7d1ee775b68939cf77d1" headers: {} responses: OK: @@ -4192,5 +4242,34 @@ tags: - name: Script description: Query information about specific scripts (Smart Contracts) x-tag-expanded: false + - name: Ogmios + description: | + Various stateless queries against Ogmios v6 instance. Please note that ogmios follows JSON-RPC 2.0 method, the example spec on koios.rest is *ONLY* for `queryNetwork/tip`, + but all the methods listed below are all accepted. Instead of duplicating specs, we would refer you directly to Ogmios documentation [here](https://ogmios.dev/api) for complete specs. + +
+
+ Note that for queries to be stateless across instances on the globe, we cannot acquire local state as successive calls will be across different instances. Also, we'd want to avoid getting an instance DDoS'd with large queries. + Thus, we will only expose the following methods from monitoring servers, instance providers can expose entire ogmios endpoints if desirable: +
+ + + ### Network + - [queryNetwork/blockHeight](https://ogmios.dev/api/#operation-publish-/?QueryNetworkBlockHeight) + - [queryNetwork/genesisConfiguration](https://ogmios.dev/api/#operation-publish-/?QueryNetworkGenesisConfiguration) + - [queryNetwork/startTime](https://ogmios.dev/api/#operation-publish-/?QueryNetworkStartTime) + - [queryNetwork/tip](https://ogmios.dev/api/#operation-publish-/?QueryNetworkTip) + ### Ledger-State + - [queryLedgerState/epoch](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateEpoch) + - [queryLedgerState/eraStart](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateEraStart) + - [queryLedgerState/eraSummaries](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateEraSummaries) + - [queryLedgerState/liveStakeDistribution](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateLiveStakeDistribution) + - [queryLedgerState/protocolParameters](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateProtocolParameters) + - [queryLedgerState/proposedProtocolParameters](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateProposedProtocolParameters) + - [queryLedgerState/stakePools](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateStakePools) + ### Transactions + - [submitTransaction](https://ogmios.dev/mini-protocols/local-tx-submission/#submitting-transactions) + - [evaluateTransaction](https://ogmios.dev/mini-protocols/local-tx-submission/#evaluating-transactions) + x-tag-expanded: true security: - bearerAuth: [] diff --git a/specs/results/koiosapi-preview.yaml b/specs/results/koiosapi-preview.yaml index 25db005a..df56edef 100644 --- a/specs/results/koiosapi-preview.yaml +++ b/specs/results/koiosapi-preview.yaml @@ -1584,43 +1584,30 @@ paths: $ref: "#/components/responses/NotFound" summary: Datum Information description: List of datum information for given datum hashes - /ogmios/?EvaluateTransaction: #ogmios-api + /ogmios/: #ogmios-api post: tags: - Ogmios - x-code-samples: - - lang: "Shell" - source: | - # Assuming ${data} contains EvaluateTransaction payload as documented on Ogmios v6 site. - curl -X POST \ - --header "Content-Type: application/cbor" \ - --data-binary ${data} https://api.koios.rest/api/ogmios/?EvaluateTransaction + requestBody: + $ref: "#/components/requestBodies/ogmios" responses: "200": - description: OK + description: Current tip of the chain, identified by a slot and a block header hash. + content: + application/json: + schema: + $ref: "#/components/schemas/ogmiostip" "400": description: An error occured while submitting transaction. - summary: Evaluate Transaction - description: Evaluate execution units of scripts in a well-formed transaction. Please refer to Ogmios documentation [here](https://ogmios.dev/api/#operation-publish-/?EvaluateTransaction) for complete spec - /ogmios/?SubmitTransaction: #ogmios-api - post: - tags: - - Ogmios - x-code-samples: - - lang: "Shell" - source: | - # Assuming ${data} contains a CBOR-serialized signed transaction (base16-encoded) as documented on Ogmios v6 site. - curl -X POST \ - --header "Content-Type: application/cbor" \ - --data-binary ${data} https://api.koios.rest/api/ogmios/?SubmitTransaction - responses: - "200": - description: OK - "400": - description: An error occured while querying transaction. - summary: Submit Transaction - description: Submit a signed and serialized transaction to the network. Please refer to Ogmios documentation [here](https://ogmios.dev/api/#operation-publish-/?SubmitTransaction) for complete spec + summary: Query Example + description: | + Query the current tip of the Network. +
+
+ We do support transparent forwarding for various methods from Ogmios, you can read about those here. +
+ components: parameters: select: @@ -2257,6 +2244,43 @@ components: - 206f6da5b0b0de45605a95f5ce7e172be9674550f7dde3838c45cbf24bab8b00#0 - f1592b29b79ae85d753913dd25644c60925a4a0683979faa33832fead4b4bd9c#0 _extended: false + ogmios: + content: + application/json: + schema: + required: + - jsonrpc + - method + type: object + properties: + jsonrpc: + format: text + type: string + description: Identifier for JSON-RPC 2.0 standard + example: "2.0" + method: + format: text + type: string + description: The Ogmios method to be called (see more details [here](#tag--Ogmios)) + enum: + - "queryNetwork/blockHeight" + - "queryNetwork/genesisConfiguration" + - "queryNetwork/startTime" + - "queryNetwork/tip" + - "queryLedgerState/epoch" + - "queryLedgerState/eraStart" + - "queryLedgerState/eraSummaries" + - "queryLedgerState/liveStakeDistribution" + - "queryLedgerState/protocolParameters" + - "queryLedgerState/proposedProtocolParameters" + - "queryLedgerState/stakePools" + - "submitTransaction" + - "evaluateTransaction" + example: "queryNetwork/tip" + params: + type: object + description: Any parameters relevant to the specific method to be called + nullable: true securitySchemes: bearerAuth: type: http @@ -2868,6 +2892,7 @@ components: nullable: true epoch_params: type: array + description: Epoch parameters (all fields nullable for pre-Shelley/Gougen epochs except first block hash) items: properties: epoch_no: @@ -4152,6 +4177,31 @@ components: $ref: "#/components/schemas/script_info/items/properties/value" bytes: $ref: "#/components/schemas/script_info/items/properties/bytes" + ogmiostip: + type: object + properties: + jsonrpc: + format: text + type: string + description: Identifier for JSON-RPC 2.0 standard + example: "2.0" + method: + format: text + type: string + description: The Ogmios method that was called in the request + example: "queryNetwork/tip" + result: + type: object + description: Result of the query + properties: + slot: + type: number + description: Absolute slot number on chain + example: 59886800 + id: + type: string + description: Block Hash (Blake2b 32-byte hash digest, encoded in base16) + example: "df5678c9774b7bc8c60a4c83b63c3676e618640ad05f7d1ee775b68939cf77d1" headers: {} responses: OK: @@ -4192,5 +4242,34 @@ tags: - name: Script description: Query information about specific scripts (Smart Contracts) x-tag-expanded: false + - name: Ogmios + description: | + Various stateless queries against Ogmios v6 instance. Please note that ogmios follows JSON-RPC 2.0 method, the example spec on koios.rest is *ONLY* for `queryNetwork/tip`, + but all the methods listed below are all accepted. Instead of duplicating specs, we would refer you directly to Ogmios documentation [here](https://ogmios.dev/api) for complete specs. + +
+
+ Note that for queries to be stateless across instances on the globe, we cannot acquire local state as successive calls will be across different instances. Also, we'd want to avoid getting an instance DDoS'd with large queries. + Thus, we will only expose the following methods from monitoring servers, instance providers can expose entire ogmios endpoints if desirable: +
+ + + ### Network + - [queryNetwork/blockHeight](https://ogmios.dev/api/#operation-publish-/?QueryNetworkBlockHeight) + - [queryNetwork/genesisConfiguration](https://ogmios.dev/api/#operation-publish-/?QueryNetworkGenesisConfiguration) + - [queryNetwork/startTime](https://ogmios.dev/api/#operation-publish-/?QueryNetworkStartTime) + - [queryNetwork/tip](https://ogmios.dev/api/#operation-publish-/?QueryNetworkTip) + ### Ledger-State + - [queryLedgerState/epoch](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateEpoch) + - [queryLedgerState/eraStart](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateEraStart) + - [queryLedgerState/eraSummaries](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateEraSummaries) + - [queryLedgerState/liveStakeDistribution](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateLiveStakeDistribution) + - [queryLedgerState/protocolParameters](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateProtocolParameters) + - [queryLedgerState/proposedProtocolParameters](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateProposedProtocolParameters) + - [queryLedgerState/stakePools](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateStakePools) + ### Transactions + - [submitTransaction](https://ogmios.dev/mini-protocols/local-tx-submission/#submitting-transactions) + - [evaluateTransaction](https://ogmios.dev/mini-protocols/local-tx-submission/#evaluating-transactions) + x-tag-expanded: true security: - bearerAuth: [] diff --git a/specs/templates/3-api-requestBodies.yaml b/specs/templates/3-api-requestBodies.yaml index 4ef376b5..38cfe762 100644 --- a/specs/templates/3-api-requestBodies.yaml +++ b/specs/templates/3-api-requestBodies.yaml @@ -381,3 +381,40 @@ requestBodies: - ##utxo_ref1_rb## - ##utxo_ref2_rb## _extended: false + ogmios: + content: + application/json: + schema: + required: + - jsonrpc + - method + type: object + properties: + jsonrpc: + format: text + type: string + description: Identifier for JSON-RPC 2.0 standard + example: "2.0" + method: + format: text + type: string + description: The Ogmios method to be called (see more details [here](#tag--Ogmios)) + enum: + - "queryNetwork/blockHeight" + - "queryNetwork/genesisConfiguration" + - "queryNetwork/startTime" + - "queryNetwork/tip" + - "queryLedgerState/epoch" + - "queryLedgerState/eraStart" + - "queryLedgerState/eraSummaries" + - "queryLedgerState/liveStakeDistribution" + - "queryLedgerState/protocolParameters" + - "queryLedgerState/proposedProtocolParameters" + - "queryLedgerState/stakePools" + - "submitTransaction" + - "evaluateTransaction" + example: "queryNetwork/tip" + params: + type: object + description: Any parameters relevant to the specific method to be called + nullable: true \ No newline at end of file diff --git a/specs/templates/4-api-schemas.yaml b/specs/templates/4-api-schemas.yaml index 942a0582..1e13adf5 100644 --- a/specs/templates/4-api-schemas.yaml +++ b/specs/templates/4-api-schemas.yaml @@ -604,6 +604,7 @@ schemas: nullable: true epoch_params: type: array + description: Epoch parameters (all fields nullable for pre-Shelley/Gougen epochs except first block hash) items: properties: epoch_no: @@ -1888,3 +1889,28 @@ schemas: $ref: "#/components/schemas/script_info/items/properties/value" bytes: $ref: "#/components/schemas/script_info/items/properties/bytes" + ogmiostip: + type: object + properties: + jsonrpc: + format: text + type: string + description: Identifier for JSON-RPC 2.0 standard + example: "2.0" + method: + format: text + type: string + description: The Ogmios method that was called in the request + example: "queryNetwork/tip" + result: + type: object + description: Result of the query + properties: + slot: + type: number + description: Absolute slot number on chain + example: 59886800 + id: + type: string + description: Block Hash (Blake2b 32-byte hash digest, encoded in base16) + example: "df5678c9774b7bc8c60a4c83b63c3676e618640ad05f7d1ee775b68939cf77d1" diff --git a/specs/templates/api-main.yaml b/specs/templates/api-main.yaml index 86168694..cecdebba 100644 --- a/specs/templates/api-main.yaml +++ b/specs/templates/api-main.yaml @@ -1439,43 +1439,30 @@ paths: $ref: "#/components/responses/NotFound" summary: Datum Information description: List of datum information for given datum hashes - /ogmios/?EvaluateTransaction: #ogmios-api + /ogmios/: #ogmios-api post: tags: - Ogmios - x-code-samples: - - lang: "Shell" - source: | - # Assuming ${data} contains EvaluateTransaction payload as documented on Ogmios v6 site. - curl -X POST \ - --header "Content-Type: application/cbor" \ - --data-binary ${data} https://api.koios.rest/api/ogmios/?EvaluateTransaction + requestBody: + $ref: "#/components/requestBodies/ogmios" responses: "200": - description: OK + description: Current tip of the chain, identified by a slot and a block header hash. + content: + application/json: + schema: + $ref: "#/components/schemas/ogmiostip" "400": description: An error occured while submitting transaction. - summary: Evaluate Transaction - description: Evaluate execution units of scripts in a well-formed transaction. Please refer to Ogmios documentation [here](https://ogmios.dev/api/#operation-publish-/?EvaluateTransaction) for complete spec - /ogmios/?SubmitTransaction: #ogmios-api - post: - tags: - - Ogmios - x-code-samples: - - lang: "Shell" - source: | - # Assuming ${data} contains a CBOR-serialized signed transaction (base16-encoded) as documented on Ogmios v6 site. - curl -X POST \ - --header "Content-Type: application/cbor" \ - --data-binary ${data} https://api.koios.rest/api/ogmios/?SubmitTransaction - responses: - "200": - description: OK - "400": - description: An error occured while querying transaction. - summary: Submit Transaction - description: Submit a signed and serialized transaction to the network. Please refer to Ogmios documentation [here](https://ogmios.dev/api/#operation-publish-/?SubmitTransaction) for complete spec + summary: Query Example + description: | + Query the current tip of the Network. +
+
+ We do support transparent forwarding for various methods from Ogmios, you can read about those here. +
+ components: #!params!# #!requestBodies!# @@ -1525,5 +1512,34 @@ tags: - name: Script description: Query information about specific scripts (Smart Contracts) x-tag-expanded: false + - name: Ogmios + description: | + Various stateless queries against Ogmios v6 instance. Please note that ogmios follows JSON-RPC 2.0 method, the example spec on koios.rest is *ONLY* for `queryNetwork/tip`, + but all the methods listed below are all accepted. Instead of duplicating specs, we would refer you directly to Ogmios documentation [here](https://ogmios.dev/api) for complete specs. + +
+
+ Note that for queries to be stateless across instances on the globe, we cannot acquire local state as successive calls will be across different instances. Also, we'd want to avoid getting an instance DDoS'd with large queries. + Thus, we will only expose the following methods from monitoring servers, instance providers can expose entire ogmios endpoints if desirable: +
+ + + ### Network + - [queryNetwork/blockHeight](https://ogmios.dev/api/#operation-publish-/?QueryNetworkBlockHeight) + - [queryNetwork/genesisConfiguration](https://ogmios.dev/api/#operation-publish-/?QueryNetworkGenesisConfiguration) + - [queryNetwork/startTime](https://ogmios.dev/api/#operation-publish-/?QueryNetworkStartTime) + - [queryNetwork/tip](https://ogmios.dev/api/#operation-publish-/?QueryNetworkTip) + ### Ledger-State + - [queryLedgerState/epoch](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateEpoch) + - [queryLedgerState/eraStart](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateEraStart) + - [queryLedgerState/eraSummaries](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateEraSummaries) + - [queryLedgerState/liveStakeDistribution](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateLiveStakeDistribution) + - [queryLedgerState/protocolParameters](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateProtocolParameters) + - [queryLedgerState/proposedProtocolParameters](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateProposedProtocolParameters) + - [queryLedgerState/stakePools](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateStakePools) + ### Transactions + - [submitTransaction](https://ogmios.dev/mini-protocols/local-tx-submission/#submitting-transactions) + - [evaluateTransaction](https://ogmios.dev/mini-protocols/local-tx-submission/#evaluating-transactions) + x-tag-expanded: true security: - bearerAuth: []