Fix specs for ogmios providing an example alongwith list of methods s…

…upported
cardano-community · Nov 3, 2023 · 87e4756 · 87e4756
1 parent 907503f
commit 87e4756
Show file tree

Hide file tree

Showing 8 changed files with 541 additions and 146 deletions.
diff --git a/html/index.html b/html/index.html
@@ -22,7 +22,7 @@
     </div-->
     <div>
       <link rel="stylesheet" id="ct-google-fonts-css" href="//fonts.googleapis.com/css?family=Montserrat%3A500%2Cregular%2C300%2C700%2C200%7COpen+Sans%3A300%2C700&amp;subset=latin%2Clatin-ext%2Cvietnamese%2Ccyrillic-ext%2Ccyrillic%2Cgreek%2Cgreek-ext&amp;ver=5.9" type="text/css" media="all">
-      <rapi-doc spec-url = "koiosapi.yaml" allow-spec-url-load="true" allow-spec-file-load="false" show-header="true" show-info='true' allow-server-selection="false" default-api-server="https://api.koios.rest/api" allow-authentication="false" allow-api-list-style-selection="true" render-style="focused" header-color="#222" primary-color="#49cc90" schema-style='table' allow-try="true" mono-font="Consolas" regular-font='Montserrat' heading-text="" on-nav-tag-click="expand-collapse" update-route="true" bg-color="#111" text-color="#ddd" use-path-in-nav-bar="false" nav-bg-color="#222" nav-item-spacing="default" show-components="false" fill-request-fields-with-example="true" schema-style='table' default-schema-tab="schema" schema-description-expanded="true" schema-expand-level="1" goto-path="get-/tip" load-fonts="true" font-size="default" info-description-headings-in-navbar="true" show-method-in-nav-bar="as-colored-text" allow-schema-description-expand-toggle="false" show-curl-before-try="true">
+      <rapi-doc spec-url = "koiosapi.yaml" allow-spec-url-load="true" allow-spec-file-load="false" show-header="true" show-info='true' allow-server-selection="false" default-api-server="https://api.koios.rest/api/v1" allow-authentication="true" allow-api-list-style-selection="true" render-style="focused" header-color="#222" primary-color="#49cc90" schema-style='table' allow-try="true" mono-font="Consolas" regular-font='Montserrat' heading-text="" on-nav-tag-click="show-description" update-route="true" bg-color="#111" text-color="#ddd" use-path-in-nav-bar="false" nav-bg-color="#222" nav-item-spacing="default" show-components="false" fill-request-fields-with-example="true" schema-style='table' default-schema-tab="schema" schema-description-expanded="false" schema-expand-level="1" goto-path="get-/tip" load-fonts="true" font-size="default" info-description-headings-in-navbar="true" show-method-in-nav-bar="as-colored-text" nav-active-item-marker="colored-block" allow-schema-description-expand-toggle="true" show-curl-before-try="true" schema-hide-read-only="never">
         <img slot="logo" src="/images/logo.png" style="height:100px;padding-left:20px;padding-right:100px"/>
       </rapi-doc>
     </div>

diff --git 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.
 
+        <br>
+        <div style="background-color: #222; padding: 12px 0px 12px 12px;border-left: 5px solid  rgb(173, 44, 44);font-size: var(--font-size-regular);">
+        We do support transparent forwarding for various methods from Ogmios, you can read about those <a href="#tag--Ogmios">here</a>.
+        </div>
+        
 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.
+
+        <br>
+        <div style="background-color: #222; padding: 12px 0px 12px 12px;border-left: 5px solid  rgb(173, 44, 44);font-size: var(--font-size-regular);">
+        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. Additionally, `queryLedgerState/utxo` method is removed to avoid DDoS impacts.
+        Thus, we only expose the following methods from monitoring servers, instance providers can expose entire ogmios endpoints if desirable:
+        </div>
+
+
+        ### 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
@@ -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.
 
+        <br>
+        <div style="background-color: #222; padding: 12px 0px 12px 12px;border-left: 5px solid  rgb(173, 44, 44);font-size: var(--font-size-regular);">
+        We do support transparent forwarding for various methods from Ogmios, you can read about those <a href="#tag--Ogmios">here</a>.
+        </div>
+        
 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.
+
+        <br>
+        <div style="background-color: #222; padding: 12px 0px 12px 12px;border-left: 5px solid  rgb(173, 44, 44);font-size: var(--font-size-regular);">
+        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. Additionally, `queryLedgerState/utxo` method is removed to avoid DDoS impacts.
+        Thus, we only expose the following methods from monitoring servers, instance providers can expose entire ogmios endpoints if desirable:
+        </div>
+
+
+        ### 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: []