WIP openapi spec for cic-cache-server

apps/cic-cache/doc/openapi/server.yml

@@ -1,4 +1,4 @@
-openapi: "3.0.3"
+openapi: "3.0.2"
 info:
   title: Grassroots Economics CIC Cache
   description: Cache of processed transaction data from Ethereum blockchain and worker queues
@@ -12,8 +12,26 @@ info:
   version: 0.1.0
 
 paths:
-  /tx/{offset}/{limit}:
-    description: Bloom filter for batch of latest transactions
+  /defaultlimit:
+    summary: The default limit value of result sets.
+    get:
+      tags:
+        - transactions
+      description:
+        Retrieve default limit
+      operationId: limit.default
+      responses:
+        200:
+          description: Limit query successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Limit"
+
+
+  /tx/{offset}/{limit}/{block_offset}/{block_end}:
+    summary: Bloom filter for batch of latest transactions
+    description: Generates a bloom filter of the specified transactions in the database. Any path query part having a value of zero will be discarded.
     get:
       tags:
         - transactions
@@ -32,15 +50,28 @@ paths:
     parameters:
     - name: offset
       in: path
+      required: true
       schema:
         type: integer
         format: int32
     - name: limit
       in: path
+      required: true
+      schema:
+        type: integer
+        format: int32
+    - name: block_offset
+      in: path
+      required: true
+      schema:
+        type: integer
+        format: int32
+    - name: block_end
+      in: path
+      required: true
       schema:
         type: integer
         format: int32
-
 
   /tx/{address}/{offset}/{limit}:
     description: Bloom filter for batch of latest transactions by account
@@ -49,7 +80,7 @@ paths:
         - transactions
       description:
         Retrieve transactions
-      operationId: tx.get
+      operationId: tx.get.user
       responses:
         200:
           description: Transaction query successful. 
@@ -67,22 +98,27 @@ paths:
         type: string
     - name: offset
       in: path
+      required: true
       schema:
         type: integer
         format: int32
     - name: limit
       in: path
+      required: true
       schema:
         type: integer
         format: int32
 
 components:
   schemas:
+    Limit:
+      type: integer
+      format: int32
     BlocksBloom:
       type: object
       properties:
         low:
-          type: int
+          type: integer
           format: int32
           description: The lowest block number included in the filter
         block_filter:
@@ -97,6 +133,12 @@ components:
           type: string
           description: Hashing algorithm (currently only using sha256)
         filter_rounds:
-          type: int
+          type: integer
           format: int32
           description: Number of hash rounds used to create the filter
+
+  examples:
+    data_last:
+      summary: Get the latest cached transactions. 
+      description: "Get the latest cached transactions. The maximum number of transactions returned is the value returned by the `/defaultlimit` query"
+      value: "/tx"