TranslatorReasonerAPI.yaml

openapi: 3.0.1
info:
  description: OpenAPI for NCATS Biomedical Translator Reasoners
  version: 0.9.3-dev
  title: OpenAPI for NCATS Biomedical Translator Reasoners
  contact:
    email: edeutsch@systemsbiology.org
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: INSERT-URL-HERE
externalDocs:
  description: >-
    Documentation for the NCATS Biomedical Translator Reasoners web services
  url: https://github.com/NCATS-Tangerine/NCATS-ReasonerStdAPI
tags:
  - name: predicates
    description: Get supported relationships by source and target
    externalDocs:
      description: Documentation for the reasoner predicates function
      url: http://reasonerhost.ncats.io/overview.html#predicates
  - name: query
    description: Query reasoner using a predefined question type
    externalDocs:
      description: Documentation for the reasoner query function
      url: http://reasonerhost.ncats.io/overview.html#query
  - name: translator
  - name: reasoner
paths:
  /predicates:
    get:
      tags:
        - predicates
      summary: Get supported relationships by source and target
      responses:
        '200':
          description: Predicates by source and target
          content:
            application/json:
              schema:
                description: Source map
                type: object
                additionalProperties:
                  description: Target map
                  type: object
                  additionalProperties:
                    description: Array of predicates
                    type: array
                    items:
                      type: string
                example:
                  'biolink:ChemicalSubstance':
                    'biolink:Gene':
                      - biolink:directly_interacts_with
                      - biolink:decreases_activity_of
  /query:
    post:
      tags:
        - query
      summary: Query reasoner via one of several inputs
      description: ''
      operationId: query
      requestBody:
        description: Query information to be submitted
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Query'
      responses:
        '200':
          description: >-
            OK. There may or may not be results. Note that some of the provided
            identifiers may not have been recognized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '400':
          description: >-
            Bad request. The request is invalid according to this OpenAPI
            schema OR a specific identifier is believed to be invalid somehow
            (not just unrecognized).
          content:
            application/json:
              schema:
                type: string
        '500':
          description: >-
            Internal server error.
          content:
            application/json:
              schema:
                type: string
        '501':
          description: >-
            Not implemented.
          content:
            application/json:
              schema:
                type: string
      x-swagger-router-controller: swagger_server.controllers.query_controller
components:
  schemas:
    Query:
      x-body-name: request_body
      type: object
      properties:
        message:
          $ref: '#/components/schemas/Message'
      additionalProperties: true
      required:
        - message
    Response:
      type: object
      properties:
        message:
          $ref: '#/components/schemas/Message'
        status:
          description: >-
            One of a standardized set of short codes,
            e.g. Success, QueryNotTraversable, KPsNotAvailable
          type: string
        description:
          description: A brief human-readable description of the outcome
          type: string
        logs:
          type: array
          items:
            $ref: '#/components/schemas/LogEntry'
      required:
        - message
    Message:
      type: object
      properties:
        results:
          description: >-
            List of all returned potential answers for the query posed
          type: array
          items:
            $ref: '#/components/schemas/Result'
        query_graph:
          type: object
          description: >-
            QueryGraph object that contains a serialization of a query in the
            form of a graph
          $ref: '#/components/schemas/QueryGraph'
        knowledge_graph:
          type: object
          description: >-
            KnowledgeGraph object that contains all the nodes and edges
            referenced in any of the possible answers to the query OR
            connection information for a remote knowledge graph
          $ref: '#/components/schemas/KnowledgeGraph'
      additionalProperties: false
    LogEntry:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
          description: Timestamp in ISO 8601 format
          example: '2020-09-03T18:13:49+00:00'
        level:
          type: string
          description: Logging level
          enum:
            - ERROR
            - WARNING
            - INFO
            - DEBUG
        code:
          type: string
          description: >-
            One of a standardized set of short codes
            e.g. QueryNotTraversable, KPNotAvailable, KPResponseMalformed
        message:
          type: string
          description: A human-readable log message
    Result:
      type: object
      description: One of potentially several results or answers for a query
      properties:
        node_bindings:
          type: object
          description: List of QNode-KNode bindings.
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/NodeBinding'
        edge_bindings:
          type: object
          description: List of QEdge-KEdge bindings.
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/EdgeBinding'
      required:
        - node_bindings
        - edge_bindings
    NodeBinding:
      type: object
      properties:
        kg_id:
          type: string
          description: A knowledge-graph node id, i.e. the `id` of a KNode
      required:
        - kg_id
    EdgeBinding:
      type: object
      properties:
        kg_id:
          type: string
          description: A knowledge-graph edge id, i.e. the `id` of a KEdge
      required:
        - kg_id
    KnowledgeGraph:
      type: object
      description: >-
        A thought graph associated with this result. This will commonly be a
        linear path subgraph from one concept to another, but related items
        aside of the path may be included.
      properties:
        nodes:
          type: object
          description: List of nodes in the KnowledgeGraph
          additionalProperties:
            $ref: '#/components/schemas/Node'
        edges:
          type: object
          description: List of edges in the KnowledgeGraph
          additionalProperties:
            $ref: '#/components/schemas/Edge'
      additionalProperties: true
      required:
        - nodes
        - edges
    QueryGraph:
      type: object
      description: >-
        A graph intended to be the thought path to be followed by a reasoner to
        answer the question. This graph is a representation of a question.
      properties:
        nodes:
          type: object
          description: List of nodes in the QueryGraph
          additionalProperties:
            $ref: '#/components/schemas/QNode'
        edges:
          type: object
          description: List of edges in the QueryGraph
          additionalProperties:
            $ref: '#/components/schemas/QEdge'
      additionalProperties: true
      required:
        - nodes
        - edges
    QNode:
      type: object
      description: A node in the QueryGraph
      properties:
        curie:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          example: OMIM:603903
          description: CURIE identifier for this node
        type:
          oneOf:
            - $ref: '#/components/schemas/BiolinkEntity'
            - type: array
              items:
                $ref: '#/components/schemas/BiolinkEntity'
        is_set:
          type: boolean
          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
      additionalProperties: true
    QEdge:
      type: object
      description: An edge in the QueryGraph
      properties:
        type:
          oneOf:
            - $ref: '#/components/schemas/BiolinkRelation'
            - type: array
              items:
                $ref: '#/components/schemas/BiolinkRelation'
        relation:
          type: string
          example: upregulates
          description: Lower-level relationship type of this edge
        source_id:
          type: string
          example: https://omim.org/entry/603903
          description: Corresponds to the @id of source node of this edge
        target_id:
          type: string
          example: https://www.uniprot.org/uniprot/P00738
          description: Corresponds to the @id of target node of this edge
      additionalProperties: true
      required:
        - source_id
        - target_id
    Node:
      type: object
      description: A node in the knowledge graph
      properties:
        name:
          type: string
          example: Haptoglobin
          description: Formal name of the entity
        type:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/BiolinkEntity'
        attributes:
          type: array
          description: A list of attributes describing the node
          items:
            $ref: '#/components/schemas/Attribute'
      additionalProperties: false
    Attribute:
      type: object
      description: Generic attribute for a node
      properties:
        name:
          type: string
          description: >-
            Human-readable name or label for the attribute. Should be the name
            of the semantic type term.
          example: PubMed Identifier
        value:
          example: 32529952
          description: >-
            Value of the attribute. May be any data type, including a list.
        type:
          type: string
          description: >-
            CURIE of the semantic type of the attribute, from the EDAM ontology
            if possible. If a suitable identifier does not exist, enter a
            descriptive phrase here and submit the new type for consideration
            by the appropriate authority.
          example: EDAM:data_1187
        url:
          type: string
          description: >-
            Human-consumable URL to link out and read about the attribute (not
            the node).
          example: https://pubmed.ncbi.nlm.nih.gov/32529952
        source:
          type: string
          description: Source of the attribute, as a CURIE prefix.
          example: UniProtKB
      required:
        - type
        - value
      additionalProperties: false
    Edge:
      type: object
      description: An edge in the knowledge graph linking two nodes
      properties:
        type:
          $ref: '#/components/schemas/BiolinkRelation'
        relation:
          type: string
          example: upregulates
          description: Lower-level relationship type of this edge
        source_id:
          type: string
          example: OMIM:603903
          description: >-
            Corresponds to the map key CURIE of the source node of this edge
        target_id:
          type: string
          example: UniProtKB:P00738
          description: >-
            Corresponds to the map key CURIE of the target node of this edge
        attributes:
          type: array
          description: A list of additional attributes for this edge
          items:
            $ref: '#/components/schemas/Attribute'
      additionalProperties: false
      required:
        - source_id
        - target_id
    BiolinkEntity:
      description: >-
        CURIE for a Biolink class, NamedThing or a child thereof (PascalCase)
      type: string
      pattern: ^biolink:[A-Z][a-zA-Z]*$
      externalDocs:
        description: Biolink model entities
        url: https://biolink.github.io/biolink-model/docs/NamedThing.html
      example: biolink:PhenotypicFeature
    BiolinkRelation:
      description: >-
        CURIE for a Biolink slot, related_to or a child thereof (snake_case)
      type: string
      pattern: ^biolink:[a-z][a-z_]*$
      externalDocs:
        description: Biolink model relations
        url: https://biolink.github.io/biolink-model/docs/related_to.html
      example: biolink:interacts_with