bte/service provider trapi: update comments, some minor fields

Author: colleenXu

biothings_explorer/service-provider-trapi.yaml

@@ -1,4 +1,6 @@
 openapi: 3.0.3
+## made this document by copying https://github.com/NCATS-Tangerine/translator-api-registry/blob/master/biothings_explorer/smartapi.yaml
+##   section-by-section and adjusting when needed
 info:
   contact:
     email: [email protected]
@@ -13,12 +15,15 @@ info:
   title: Service Provider TRAPI
   version: 2.8.1
   x-trapi:
-    version: 1.2.0
+    version: 1.2.0    ## will update to 1.3 once all instances have trapi1.3 code
     asyncquery: true
     operations:
-      - lookup
-    ## look at https://standards.ncats.io/operation.json for details
-    ## perhaps advertise "lookup_and_score"?
+    ## look at https://standards.ncats.io/operation.json for details. was previously lookup
+      - lookup_and_score
+    ## no batch_size_limit (BTE manages IDs for QNodes and sub-queries internally)
+    ## /query endpoints have a limit of 15 requests/client/min
+    ## /meta_knowledge_graph endpoints have a limit of 30 requests/client/min
+    ## other endpoints don't have rate limits
   x-translator:
     infores: "infores:service-provider-trapi"
     biolink-version: 2.4.8
@@ -39,17 +44,18 @@ servers:
   description: Non-ITRB dev (primary internal use)
   x-maturity: development
 tags:
-- name: 1.2.0
+- name: 1.2.0    ## will update to 1.3 once all instances have trapi1.3 code
 - name: meta_knowledge_graph
 - name: query
 - name: asyncquery
 - name: translator
 - name: trapi
 - name: biothings
-## Note: BTE has custom behavior so DO NOT blindly copy-paste the TRAPI specs / schemas below
+## Note: BTE has custom behavior so DO NOT blindly copy-paste the TRAPI specs / schemas into the document below
 ##       instead go through it and copy-paste in sections as-needed
 ## examples are using MyVariant-specific query
 paths:
+  ## copied directly from TRAPI spec
   /meta_knowledge_graph:
     get:
       tags:
@@ -63,6 +69,7 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/MetaKnowledgeGraph'
+  ## modified TRAPI spec: example and BTE-specific parameters, used by developers running local instances of BTE
   /query:
     post:
       tags:
@@ -71,7 +78,6 @@ paths:
         Query Service Provider's SMARTAPI KP APIs (that have x-bte annotation) as an individual TRAPI
         service
       description: ''
-      operationId: queryTeam
       parameters:
         - description: option to choose whether or not to enable caching
           in: query
@@ -141,10 +147,19 @@ paths:
             application/json:
               schema:
                 type: string
-      x-swagger-router-controller: swagger_server.controllers.query_controller
   ## need to remove the extra stuff from server url to use this endpoint..
   ## example: https://api.bte.ncats.io/check_query_status/{id}
+  ## not TRAPI spec: BTE-specific endpoint related to asyncquery
   # /check_query_status/{id}:
+  # ## moved because smartapi-editor gave alert that a non-existent post endpoint wouldn't know what {id} is
+  #   parameters:
+  #     - description: job-id
+  #       in: path
+  #       name: id
+  #       required: true
+  #       ## Cache refreshing means this will be changing pretty often, so not including an example
+  #       schema:
+  #         type: string
   #   get:
   #     tags:
   #       - asyncquery
@@ -155,15 +170,7 @@ paths:
   #       the Response.
   #     description: ''
   #     parameters:
-  #       - description: job-id
-  #         ## could add example like hY2BrhJfcN (successfully completed) or ovllMzFfCe (failed)
-  #         in: path
-  #         name: id
-  #         required: true
-  #          ## Cache refreshing means this will be changing pretty often, so not including an example
-  #         schema:
-  #           type: string
-  #         - description: option to override original query log level
+  #       - description: option to override original query log level
   #         in: query
   #         name: log_level
   #         required: false
@@ -203,7 +210,7 @@ paths:
   #                   properties:
   #                     response:
   #                       $ref: '#/components/schemas/Response'
-  ## note that the AsyncQuery schema is changed to make callback optional
+  ## modified TRAPI spec: summary sections tell users that AsyncQuery schema was changed to make callback optional
   /asyncquery:
     post:
       tags:
@@ -295,6 +302,13 @@ paths:
               schema:
                 type: string
 components:
+  ## look for comments to see parts that have been modified for BTE
+  ## - Query: comment out workflow.allOf section since the $ref breaks execution of 
+  ##          BTE's api-schema-builder/openapi-validator-middleware
+  ## - AsyncQuery: callback property not required (commented it out of the 'required' field),
+  ##               comment out workflow.allOf section
+  ## - Response: comment out workflow.allOf section
+  ## - QNode: commented out an example for some reason
   schemas:
     Query:
       description: >-

biothings_explorer/smartapi.yaml

@@ -9,19 +9,27 @@ info:
   title: BioThings Explorer ReasonerStdAPI
   version: 2.8.1
   x-trapi:
-    version: 1.2.0
+    version: 1.2.0    ## will update to 1.3 once all instances have trapi1.3 code
     asyncquery: true
     operations:
-      - lookup
-    ## look at https://standards.ncats.io/operation.json for details
-    ## perhaps advertise "lookup_and_score"?
+    ## look at https://standards.ncats.io/operation.json for details. was previously lookup
+      - lookup_and_score
+    ## no batch_size_limit (BTE manages IDs for QNodes and sub-queries internally)
+    ## /query endpoints have a limit of 15 requests/client/min
+    ## /meta_knowledge_graph endpoints have a limit of 30 requests/client/min
+    ## other endpoints don't have rate limits
   x-translator:
     infores: "infores:biothings-explorer"
     biolink-version: 2.4.8
     component: ARA
     team:
       - Exploring Agent
 servers:
+## ITRB Production and Test are deployed manually, based on the staging instance
+## ITRB CI / staging is basically deployed manually, from main branches
+## - automatic for updates in bte-trapi-workspace main branch, but those rarely happen
+## - we could technically control what branches are used (but right now we don't do this)
+## non-ITRB dev: total manual control on updates (what branches of modules are used for updates)
 - url: https://bte.transltr.io/v1
   description: ITRB Production server
   x-maturity: production
@@ -35,17 +43,18 @@ servers:
   description: Non-ITRB dev (primary internal use)
   x-maturity: development
 tags:
-- name: 1.2.0
+- name: 1.2.0    ## will update to 1.3 once all instances have trapi1.3 code
 - name: meta_knowledge_graph
 - name: query
 - name: asyncquery
 - name: translator
 - name: trapi
 - name: biothings
-## Note: BTE has custom behavior so DO NOT blindly copy-paste the TRAPI specs / schemas below
+## Note: BTE has custom behavior so DO NOT blindly copy-paste the TRAPI specs / schemas into the document below
 ##       instead go through it and copy-paste in sections as-needed
 ## examples are using MyVariant-specific query
 paths:
+  ## copied directly from TRAPI spec
   /meta_knowledge_graph:
     get:
       tags:
@@ -59,6 +68,7 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/MetaKnowledgeGraph'
+  ## copied from /meta_knowledge_graph above and modified: BTE-specific endpoint
   /smartapi/{smartapi_id}/meta_knowledge_graph:
     get:
       tags:
@@ -80,6 +90,7 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/MetaKnowledgeGraph'
+  ## copied from /meta_knowledge_graph above and modified: BTE-specific endpoint
   /team/{team_name}/meta_knowledge_graph:
     get:
       tags:
@@ -105,12 +116,12 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/MetaKnowledgeGraph'
+  ## modified TRAPI spec: example and BTE-specific parameters, used by developers running local instances of BTE
   /query:
     post:
       tags:
         - query
       summary: Query BioThings Explorer TRAPI API as ARA with a TRAPI query
-      operationId: query
       parameters:
         - description: option to choose whether or not to enable caching
           in: query
@@ -180,13 +191,12 @@ paths:
             application/json:
               schema:
                 type: string
-      x-swagger-router-controller: swagger_server.controllers.query_controller
+  ## copied from /query above and modified: BTE-specific endpoint  
   /smartapi/{smartapi_id}/query:
     post:
       tags:
         - query
       summary: Query individual SmartAPI KP API (that has x-bte annotation) as a TRAPI API
-      operationId: querySmartAPI
       parameters:
         - description: SmartAPI ID of an API, you can get it from https://smart-api.info/registry
           in: path
@@ -263,7 +273,7 @@ paths:
             application/json:
               schema:
                 type: string
-      x-swagger-router-controller: swagger_server.controllers.query_controller
+  ## copied from /query above and modified: BTE-specific endpoint
   /team/{team_name}/query:
     post:
       tags:
@@ -272,7 +282,6 @@ paths:
         Query an individual Translator team's SMARTAPI KP APIs (that have x-bte annotation) as an individual TRAPI
         service using team name
       description: ''
-      operationId: queryTeam
       parameters:
         - description: Translator Team Name, e.g. Service Provider, Multiomics Provider
           in: path
@@ -353,8 +362,17 @@ paths:
             application/json:
               schema:
                 type: string
-      x-swagger-router-controller: swagger_server.controllers.query_controller
+  ## not TRAPI spec: BTE-specific endpoint related to asyncquery
   /check_query_status/{id}:
+  ## moved because smartapi-editor gave alert that a non-existent post endpoint wouldn't know what {id} is
+    parameters:
+      - description: job-id
+        in: path
+        name: id
+        required: true
+        ## Cache refreshing means this will be changing pretty often, so not including an example
+        schema:
+          type: string
     get:
       tags:
         - asyncquery
@@ -365,13 +383,6 @@ paths:
         the Response.
       description: ''
       parameters:
-        - description: job-id
-          in: path
-          name: id
-          required: true
-          ## Cache refreshing means this will be changing pretty often, so not including an example
-          schema:
-            type: string
         - description: option to override original query log level
           in: query
           name: log_level
@@ -412,7 +423,7 @@ paths:
                     properties:
                       response:
                         $ref: '#/components/schemas/Response'
-  ## note that the AsyncQuery schema is changed to make callback optional
+  ## modified TRAPI spec: summary sections tell users that AsyncQuery schema was changed to make callback optional  
   /asyncquery:
     post:
       tags:
@@ -498,6 +509,7 @@ paths:
             application/json:
               schema:
                 type: string
+  ## copied from /asyncquery above and modified: BTE-specific endpoint
   /smartapi/{smartapi_id}/asyncquery:
     post:
       tags:
@@ -592,6 +604,7 @@ paths:
             application/json:
               schema:
                 type: string
+  ## copied from /asyncquery above and modified: BTE-specific endpoint
   /team/{team_name}/asyncquery:
     post:
       tags:
@@ -692,6 +705,13 @@ paths:
               schema:
                 type: string
 components:
+  ## look for comments to see parts that have been modified for BTE
+  ## - Query: comment out workflow.allOf section since the $ref breaks execution of 
+  ##          BTE's api-schema-builder/openapi-validator-middleware
+  ## - AsyncQuery: callback property not required (commented it out of the 'required' field),
+  ##               comment out workflow.allOf section
+  ## - Response: comment out workflow.allOf section
+  ## - QNode: commented out an example for some reason
   schemas:
     Query:
       description: >-