TranslatorReasonersAPI.yaml

openapi: 3.0.1
info:
  description: OpenAPI for NCATS Biomedical Translator Reasoners
  version: 0.9.2
  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: "{{url}}"
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'
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:
                  chemical_substance:
                    gene:
                      - directly_interacts_with
                      - 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: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '400':
          description: Invalid status value
      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
    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: true
    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'
      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'
        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'
      additionalProperties: true
    Edge:
      type: object
      description: An edge in the thought subgraph linking two nodes
      properties:
        type:
          $ref: '#/components/schemas/BiolinkRelation'
        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
    BiolinkEntity:
      description: A subclass of category named_thing (snake_case)
      type: string
      externalDocs:
        description: Biolink model entities
        url: https://biolink.github.io/biolink-model/docs/NamedThing.html
      example: disease
    BiolinkRelation:
      description: A relation, i.e. child of related_to (snake_case)
      type: string
      externalDocs:
        description: Biolink model relations
        url: https://biolink.github.io/biolink-model/docs/related_to.html
      example: affects