WIP openapi spec for cic-cache-server

apps/cic-cache/cic_cache/runnable/daemons/query.py

@@ -23,6 +23,7 @@ re_transactions_all_bloom = r'/tx/(\d+)?/?(\d+)/?(\d+)?/?(\d+)?/?'
 re_transactions_account_bloom = r'/tx/user/((0x)?[a-fA-F0-9]+)(/(\d+)(/(\d+))?)?/?'
 re_transactions_all_data = r'/txa/(\d+)/?(\d+)?/?(\d+)?/?(\d+)?/?'
 re_transactions_account_data = r'/txa/user/((0x)?[a-fA-F0-9]+)(/(\d+)(/(\d+))?)?/?'
+re_default_limit = r'/defaultlimit/?'
 
 DEFAULT_LIMIT = 100
 
@@ -64,6 +65,14 @@ def parse_query_any(r):
     return (offset, limit, block_offset, block_end,)
 
 
+def process_default_limit(session, env):
+    r = re.match(re_default_limit, env.get('PATH_INFO'))
+    if not r:
+        return None
+
+    return ('application/json', str(DEFAULT_LIMIT).encode('utf-8'),)
+
+
 def process_transactions_account_bloom(session, env):
     r = re.match(re_transactions_account_bloom, env.get('PATH_INFO'))
     if not r:

apps/cic-cache/cic_cache/runnable/daemons/server.py

@@ -12,6 +12,7 @@ import cic_cache.cli
 from cic_cache.db import dsn_from_config
 from cic_cache.db.models.base import SessionBase
 from cic_cache.runnable.daemons.query import (
+        process_default_limit,
         process_transactions_account_bloom,
         process_transactions_account_data,
         process_transactions_all_bloom,
@@ -49,6 +50,7 @@ def application(env, start_response):
             process_transactions_all_bloom,
             process_transactions_account_bloom,
             process_transactions_account_data,
+            process_default_limit,
             ]:
         r = None
         try:

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"