diff --git a/config/smartapi_exclusions.yaml b/config/smartapi_exclusions.yaml index b212767..b4c4d37 100644 --- a/config/smartapi_exclusions.yaml +++ b/config/smartapi_exclusions.yaml @@ -3,3 +3,8 @@ name: BioThings Explorer (BTE) TRAPI - id: 36f82f05705c317bac17ddae3a0ea2f0 name: Service Provider TRAPI +## temp separate registrations for TRAPI 1.5 +- id: 8d97ee37572eaaf9e74df447763fd0c5 + name: BioThings Explorer (BTE) TRAPI +- id: a0595049c9a250003c2eced0946d84f6 + name: Service Provider TRAPI diff --git a/docs/smartapi.yaml b/docs/smartapi.yaml index 0bfa623..d621624 100644 --- a/docs/smartapi.yaml +++ b/docs/smartapi.yaml @@ -15,12 +15,11 @@ info: biolink-version: "4.1.6" infores: "infores:biothings-explorer" x-trapi: - version: 1.4.0 + version: 1.5.0-beta asyncquery: true operations: ## look at https://standards.ncats.io/operation.json for details. - ## could use lookup_and_score in the future? - - lookup + - lookup_and_score ## /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 @@ -30,10 +29,11 @@ info: default: url: "https://raw.githubusercontent.com/NCATS-Tangerine/translator-api-registry/master/biothings_explorer/sri-test-bte-ara.json" servers: -## ITRB Production and Test deployments are made by ITRB, based on the staging instance -## ITRB CI / staging deployments are made by our team (will add details later) -## non-ITRB dev: deployments are made by our team -## we have full control on when / what branches for modules are used +## ITRB Production and Test deployments are made by ITRB when we make a change request. +## These deployments use a snapshot of the staging instance. +## ITRB CI / staging deployments are made by our team. +## non-ITRB dev deployments are made by our team. +## We have full control on when / what branches for modules are used - url: https://bte.transltr.io/v1 description: ITRB Production server x-maturity: production @@ -47,7 +47,7 @@ servers: description: Non-ITRB dev (internal use) x-maturity: development tags: -- name: 1.4.0 +- name: 1.5.0-beta - name: meta_knowledge_graph - name: query - name: asyncquery @@ -134,19 +134,14 @@ paths: tags: - query summary: Initiate a TRAPI-format query to BTE (operating as an ARA) and wait to receive a Response - parameters: - - description: option to choose whether or not to enable caching - in: query - name: caching - required: false - schema: - type: boolean - - description: dryrun a query (logs the queries BTE will make) - in: query - name: dryrun - required: false - schema: - type: boolean + ## old feature: not sure if it still works + # parameters: + # - description: dryrun a query (logs the queries BTE will make) + # in: query + # name: dryrun + # required: false + # schema: + # type: boolean requestBody: description: Query information to be submitted required: true @@ -235,18 +230,13 @@ paths: example: 09c8782d9f4027712e65b95424adba79 ## MyVariant schema: type: string - - description: option to choose whether or not to enable caching - in: query - name: caching - required: false - schema: - type: boolean - - description: dryrun a query (logs the queries BTE will make) - in: query - name: dryrun - required: false - schema: - type: boolean + ## old feature: not sure if it still works + # - description: dryrun a query (logs the queries BTE will make) + # in: query + # name: dryrun + # required: false + # schema: + # type: boolean requestBody: description: Query information to be submitted required: true @@ -343,18 +333,13 @@ paths: - Multiomics Provider - Text Mining Provider - Service Provider - - description: option to choose whether or not to enable caching - in: query - name: caching - required: false - schema: - type: boolean - - description: dryrun a query (logs the queries BTE will make) - in: query - name: dryrun - required: false - schema: - type: boolean + ## old feature: not sure if it still works + # - description: dryrun a query (logs the queries BTE will make) + # in: query + # name: dryrun + # required: false + # schema: + # type: boolean requestBody: description: Query information to be submitted required: true @@ -439,19 +424,14 @@ paths: the callback property is not included, BTE will handle the query in a polling manner: it will provide a job-id that can be used to check the status or retrieve the Response. - parameters: - - description: option to choose whether or not to enable caching - in: query - name: caching - required: false - schema: - type: boolean - - description: dryrun a query (logs the queries BTE will make) - in: query - name: dryrun - required: false - schema: - type: boolean + ## old feature: not sure if it still works + # parameters: + # - description: dryrun a query (logs the queries BTE will make) + # in: query + # name: dryrun + # required: false + # schema: + # type: boolean requestBody: description: Query information to be submitted required: true @@ -553,18 +533,13 @@ paths: example: 09c8782d9f4027712e65b95424adba79 ## MyVariant schema: type: string - - description: option to choose whether or not to enable caching - in: query - name: caching - required: false - schema: - type: boolean - - description: dryrun a query (logs the queries BTE will make) - in: query - name: dryrun - required: false - schema: - type: boolean + ## old feature: not sure if it still works + # - description: dryrun a query (logs the queries BTE will make) + # in: query + # name: dryrun + # required: false + # schema: + # type: boolean requestBody: description: Query information to be submitted required: true @@ -672,18 +647,13 @@ paths: - Multiomics Provider - Text Mining Provider - Service Provider - - description: option to choose whether or not to enable caching - in: query - name: caching - required: false - schema: - type: boolean - - description: dryrun a query (logs the queries BTE will make) - in: query - name: dryrun - required: false - schema: - type: boolean + ## old feature: not sure if it still works + # - description: dryrun a query (logs the queries BTE will make) + # in: query + # name: dryrun + # required: false + # schema: + # type: boolean requestBody: description: Query information to be submitted required: true @@ -799,6 +769,47 @@ paths: application/json: schema: type: string + ## custom endpoint: copied and modified asyncquery_status endpoint spec + /asyncquery_response/{job_id}: + get: + tags: + - asyncquery_response + summary: >- + If the previously submitted asyncquery is still pending/in-progress, this endpoint will return the same + response as the asyncquery_status endpoint (status, logs). But if the asyncquery job is finished, + the complete TRAPI response to the query will be returned + operationId: asyncquery_response + parameters: + - in: path + name: job_id + description: Identifier of the job for status request + # example: rXEOAosN3L + required: true + schema: + type: string + responses: + '200': + description: >- + Response format depends on status of the job (pending/in-progress vs finished) + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/AsyncQueryStatusResponse' + - $ref: '#/components/schemas/Response' + '404': + description: job_id not found + '501': + description: >- + Return code 501 indicates that this endpoint has not been + implemented at this site. Sites that implement /asyncquery + MUST implement /asyncquery_status/{job_id}, but those that + do not implement /asyncquery SHOULD NOT implement + /asyncquery_status. + content: + application/json: + schema: + type: string components: ## look for comments to see parts that have been modified for BTE ## also, many sections have additionalProperties: true @@ -822,7 +833,9 @@ components: type: object properties: message: - $ref: '#/components/schemas/Message' + oneOf: + - $ref: '#/components/schemas/Message' + nullable: false description: >- The query Message is a serialization of the user request. Content of the Message object depends on the intended TRAPI operation. For @@ -837,7 +850,7 @@ components: workflow: description: List of workflow steps to be executed. # oneOf: - # - $ref: http://standards.ncats.io/workflow/1.3.4/schema + # - $ref: https://standards.ncats.io/workflow/1.3.5/schema nullable: true submitter: type: string @@ -846,6 +859,14 @@ components: purpose of this optional field is to aid in the tracking of the source of queries for development and issue resolution. nullable: true + bypass_cache: + type: boolean + default: false + description: >- + Set to true in order to request that the agent obtain + fresh information from its sources in all cases where + it has a viable choice between requesting fresh information + in real time and using cached information. additionalProperties: true required: - message @@ -858,6 +879,7 @@ components: properties: callback: type: string + nullable: false format: uri pattern: ^https?:// description: >- @@ -870,7 +892,9 @@ components: does not succeed, the server SHOULD retry the POST at least once. message: - $ref: '#/components/schemas/Message' + oneOf: + - $ref: '#/components/schemas/Message' + nullable: false description: >- The query Message is a serialization of the user request. Content of the Message object depends on the intended TRAPI operation. For @@ -885,7 +909,7 @@ components: workflow: description: List of workflow steps to be executed. # oneOf: - # - $ref: http://standards.ncats.io/workflow/1.3.4/schema + # - $ref: https://standards.ncats.io/workflow/1.3.5/schema nullable: true submitter: type: string @@ -894,6 +918,14 @@ components: purpose of this optional field is to aid in the tracking of the source of queries for development and issue resolution. nullable: true + bypass_cache: + type: boolean + default: false + description: >- + Set to true in order to request that the agent obtain + fresh information from its sources in all cases where + it has a viable choice between requesting fresh information + in real time and using cached information. additionalProperties: true required: ## BTE does not require the callback property, see the asyncquery @@ -961,6 +993,7 @@ components: type: array items: $ref: '#/components/schemas/LogEntry' + minItems: 1 nullable: false response_url: description: >- @@ -988,7 +1021,9 @@ components: description: >- Contains the knowledge of the response (query graph, knowledge graph, and results). - $ref: '#/components/schemas/Message' + oneOf: + - $ref: '#/components/schemas/Message' + nullable: false status: description: >- One of a standardized set of short codes, @@ -1009,20 +1044,23 @@ components: type: array items: $ref: '#/components/schemas/LogEntry' - nullable: true + minItems: 0 + nullable: false workflow: description: List of workflow steps that were executed. # oneOf: - # - $ref: http://standards.ncats.io/workflow/1.3.4/schema + # - $ref: https://standards.ncats.io/workflow/1.3.5/schema nullable: true schema_version: type: string example: 1.4.0 description: Version label of the TRAPI schema used in this document + nullable: true biolink_version: type: string example: 3.1.2 description: Version label of the Biolink model used in this document + nullable: true additionalProperties: true required: - message @@ -1042,11 +1080,16 @@ components: description: >- List of all returned Result objects for the query posed. The list SHOULD NOT be assumed to be ordered. The 'score' property, - if present, MAY be used to infer result rankings. + if present, MAY be used to infer result rankings. If Results are + not expected (such as for a query Message), this property SHOULD + be null or absent. If Results are expected (such as for a response + Message) and no Results are available, this property SHOULD be an + array with 0 Results in it. type: array items: $ref: '#/components/schemas/Result' nullable: true + minItems: 0 query_graph: description: >- QueryGraph object that contains a serialization of a query in the @@ -1142,6 +1185,8 @@ components: type: array items: $ref: '#/components/schemas/NodeBinding' + minItems: 1 + nullable: false analyses: type: array description: >- @@ -1149,6 +1194,8 @@ components: See below for Analysis components. items: $ref: '#/components/schemas/Analysis' + minItems: 0 + nullable: false additionalProperties: true required: - node_bindings @@ -1164,7 +1211,9 @@ components: Binding must bind directly to node in the original Query Graph. properties: id: - $ref: '#/components/schemas/CURIE' + oneOf: + - $ref: '#/components/schemas/CURIE' + nullable: false description: >- The CURIE of a Node within the Knowledge Graph. query_id: @@ -1190,10 +1239,12 @@ components: result. items: $ref: '#/components/schemas/Attribute' - nullable: true + minItems: 0 + nullable: false additionalProperties: true required: - id + - attributes Analysis: type: object description: >- @@ -1271,6 +1322,7 @@ components: id: type: string description: The key identifier of a specific KnowledgeGraph Edge. + nullable: false attributes: type: array description: >- @@ -1280,10 +1332,12 @@ components: result. items: $ref: '#/components/schemas/Attribute' - nullable: true + minItems: 0 + nullable: false additionalProperties: true required: - id + - attributes AuxiliaryGraph: type: object description: >- @@ -1310,10 +1364,12 @@ components: Attributes of the Auxiliary Graph items: $ref: '#/components/schemas/Attribute' - nullable: true + minItems: 0 + nullable: false additionalProperties: true required: - edges + - attributes KnowledgeGraph: type: object description: >- @@ -1394,20 +1450,22 @@ components: $ref: '#/components/schemas/BiolinkEntity' minItems: 1 nullable: true - is_set: - type: boolean + set_interpretation: + type: string description: >- - Boolean that if set to true, indicates that this QNode MAY have - multiple KnowledgeGraph Nodes bound to it within each Result. - The nodes in a set should be considered as a set of independent - nodes, rather than a set of dependent nodes, i.e., the answer - would still be valid if the nodes in the set were instead returned - individually. Multiple QNodes may have is_set=True. If a QNode - (n1) with is_set=True is connected to a QNode (n2) with - is_set=False, each n1 must be connected to n2. If a QNode (n1) - with is_set=True is connected to a QNode (n2) with is_set=True, - each n1 must be connected to at least one n2. - default: false + Indicates how multiple CURIEs in the ids property MUST be + interpreted. BATCH indicates that the query is intended to be + a batch query and each CURIE is treated independently. ALL means + that all specified CURIES MUST appear in each Result. + MANY means that member CURIEs MUST form one or more + sets in the Results, and sets with more members are generally + considered more desirable that sets with fewer members. + If this property is missing or null, the default is BATCH. + enum: + - BATCH + - ALL + - MANY + nullable: true constraints: type: array description: >- @@ -1513,13 +1571,25 @@ components: categories should also be avoided. items: $ref: '#/components/schemas/BiolinkEntity' - nullable: true + minItems: 1 + nullable: false attributes: type: array description: A list of attributes describing the node items: $ref: '#/components/schemas/Attribute' - nullable: true + minItems: 0 + nullable: false + is_set: + type: boolean + description: >- + Indicates that the node represents a set of entities. + If this property is missing or null, it is assumed to be + false. + nullable: true + required: + - categories + - attributes additionalProperties: false Attribute: type: object