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

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

Hide file tree

Showing 7 changed files with 540 additions and 145 deletions.
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. 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:
+        </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. 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:
+        </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: []