gene_sharpener_api.yml

swagger: '2.0'
info:
  title: Sharpener API
  version: 1.3.0

host: sharpener.ncats.io
basePath: /api
schemes:
- "https"

paths:

  /create_gene_list:
    post:
      tags:
      - sharpener
      summary: Create a new gene list
      description: Creates a new gene list from a collection of gene symbols.
      parameters:
      - in: body
        name: query
        description: a collection of gene symbols
        required: true
        schema:
          type: array
          items:
            type: string
          example: [AURA, TP53]

      responses:
        200:
          description: successful operation
          schema:
            $ref: '#/definitions/gene_list'
            

  /transformers:
    get:
      tags:
      - sharpener
      summary: Retrieve a list of transformers
      description: Provides a list of transformers and their descriptions.
      responses:
        200:
          description: successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/transformer_info'

  /transform:
    post:
      tags:
      - sharpener
      summary: Transform a gene list
      description: Depending on the function of a transformer, creates, expands, or filters a gene list.
      parameters:
      - in: body
        name: query
        description: transformer query
        required: true
        schema:
          $ref: '#/definitions/transformer_query'

      responses:
        200:
          description: successful operation
          schema:
            $ref: '#/definitions/gene_list'
        400:
          description: bad request
          schema:
            $ref: '#/definitions/error_msg'
        404:
          description: not found
          schema:
            $ref: '#/definitions/error_msg'
        500:
          description: internal server error
          schema:
            $ref: '#/definitions/error_msg'
            
  /aggregate:
    post:
      tags:
      - sharpener
      summary: Aggregate multiple gene lists
      description: Aggregates multiple gene lists into one gene list.
      parameters:
      - in: body
        name: query
        description: aggregation query
        required: true
        schema:
          $ref: '#/definitions/aggregation_query'

      responses:
        200:
          description: successful operation
          schema:
            $ref: '#/definitions/gene_list'

  /gene_list/{gene_list_id}:
    get:
      tags:
      - sharpener
      summary: Retrieve a gene list
      description: Retrieves a gene list for a given gene-list id.
      parameters:
      - in: path
        name: gene_list_id
        description: gene-list id
        required: true
        type: string
      responses:
        200:
          description: successful operation
          schema:
            $ref: '#/definitions/gene_list'
      
  /submit:
    post:
      tags:
      -  asynchronous
      summary: Asynchronously transform a gene list
      description: Depending on the function of a transformer, creates, expands, or filters a gene list.
      parameters:
      - in: body
        name: query
        description: transformer query
        required: true
        schema:
          $ref: '#/definitions/transformer_query'

      responses:
        200:
          description: successful operation
          schema:
            $ref: '#/definitions/request'
            
  /status/{request_id}:
    get:
      tags:
      -  asynchronous
      summary: Get a status of a request
      description: Get a status of an asynchronous transformation request.
      parameters:
      - in: path
        name: request_id
        description: Id of an asynchronous transformation request.
        required: true
        type: string

      responses:
        200:
          description: successful operation
          schema:
            $ref: '#/definitions/request'
            
definitions:

  transformer_query:
    type: object
    properties:
      name:
        type: string
        description: Name of the transformer that will be executed.
      gene_list_id:
        type: string
        description: >-
          Id of the gene list that will be transformed. Required for expanders and filters; 
          should be omited for producers.
      controls:
        type: array
        items:
          $ref: '#/definitions/property'
        description: >-
          Values that control the behavior of the transformer. Names of the controls must match the names
          specified in the transformer's definition and values must match types (and possibly 
          allowed_values) specified in the transformer's definition.
    required: 
      - name
      - controls
    example: 
      name: MSigDB gene-set producer
      controls:
        - name: gene_set_name
          value: REACTOME_GLUCOSE_TRANSPORT

  gene_list:
    type: object
    properties:
      gene_list_id:
        type: string
        description: Id of the gene list.
      source:
        type: string
        description: Transformer that produced the gene list.
      attributes:
        type: array
        items:
          $ref: '#/definitions/attribute'
        description: Additional information and provenance about the gene list.
      genes:
        type: array
        items:
          $ref: '#/definitions/gene_info'
        description: Members of the gene list.
    required: 
      - gene_list_id
      - source
      - genes

  gene_info:
    type: object
    properties:
      gene_id:
        type: string
        description: >-
          Id of the gene. Preferably HGNC id; can be Entrez or ENSEMBL id if HGNC id is not available.
      identifiers:
        type: object
        properties:
          entrez:
            type: string
            description: Entrez gene id (CURIE).
            example: 'NCBIGene:100'
          hgnc:
            type: string
            description: HGNC gene id (CURIE).
            example: 'HGNC:186'
          mim:
            type: string
            description: OMIM gene id (CURIE).
            example: 'MIM:608958'
          ensembl:
            type: array
            items:
              type: string
              example: 'ENSEMBL:ENSG00000196839'
            description: ENSEMBL gene id (CURIE).
          mygene_info:
            type: string
            description: myGene.info primary id.
            example: '100'
      attributes:
        type: array
        items:
          $ref: '#/definitions/attribute'
        description: >-
          Additional information about the gene and provenance about gene-list membership. Sharpener
          will use myGene.info to add 'gene_symbol', 'synonyms', and 'gene_name' to every gene. 
          Multiple synonyms are separated by semicolons.
      source:
        type: string
        description: Name of a transformer that added gene to the gene list.
    required: 
      - gene_id

  attribute:
    type: object
    properties:
      name:
        type: string
        description: Name of the attribute.
      value:
        type: string
        description: Value of the attribute.
      source:
        type: string
        description: Transformer that produced the attribute's value.
      url:
        type: string
        description: URL for additional information.
    required: 
      - name
      - value
      - source

  property:
    type: object
    properties:
      name:
        type: string
      value:
        type: string
    required: 
      - name
      - value

  transformer_info:
    type: object
    properties:
      name:
        type: string
        description: Name of the transformer.
      label:
        type: string
        description: Short label for GUI display.
      url:
        type: string
        description: Transformer's url.
      version:
        type: string
        description: Transformer's version.
      status:
        type: string
        description: Status of the transformer, one of 'online', 'offline'.
        enum: [online,offline]
      function:
        type: string
        description: Function of the transformer, one of 'producer', 'expander', 'filter', or 'aggregator'.
        enum: [producer, expander, filter, aggregator]
      description:
        type: string
        description: Description of the transformer.
      properties:
        type: object
        description: Additional metadata for the transformer.
        properties:
          list_predicate:
            type: string
            description: Biolink model predicate describing relationship between input and output gene lists.
          member_predicate:
            type: string
            description: Biolink model predicate describing relationship between input and output genes.
          source_url:
            type: string
            description: URL for underlying data or a wrapped service.
          method:
            type: string
            description: A method used to generate output gene lists.
      parameters:
        type: array
        items:
          $ref: '#/definitions/parameter'
        description: Parameters used to control the transformer.
      required_attributes:
        type: array
        items:
          type: string
        description: Gene attributes required by the transformer.
    description: Definition of the transformer.
    required: 
      - name
      - status
      - function

  parameter:
    type: object
    properties:
      name:
        type: string
        description: Name of the parameter.
      type:
        type: string
        description: Type of the parameter, one of 'Boolean', 'int', 'double', 'string'.
        enum: [Boolean, int, double, string]
      default:
        type: string
        description: Default value of the parameter.
      biolink_class:
        type: string
        description: >- 
          Biolink class of the parameter. Applicable to producers only and only one parameter
          can have a biolink class.
      allowed_values: 
        type: array
        items:
          type: string
        description: Allowed values for the parameter.
      allowed_range: 
        type: array
        items:
          type: number
        description: Allowed range for values of the parameter.
        minItems: 2
        maxItems: 2
      suggested_values:
        type: string
        description: Suggested value range for the parameter.
      lookup_url:
        type: string
        description: URL to search for suitable parameter values. 
    required: 
      - name
      - type
      - default

  aggregation_query:
    type: object
    properties:
      operation:
        type: string
        description: Gene-list aggregation operation, one of 'union', 'intersection', 'difference','symmetric difference'.
      controls:
        type: array
        items:
          $ref: '#/definitions/property'
        description: >-
          Values that control the behavior of the aggregator. Names of the controls must match the names
          specified in the aggregator's definition and values must match types (and possibly 
          allowed_values) specified in the aggregator's definition.
      gene_list_ids:
        type: array
        items:
          type: string
        description: Ids of the gene lists to be aggregated.
        example: [gene_lis_id_1, gene_list_id_2]
    required: 
      - operation
      - gene_list_ids
      
  request:
    type: object
    properties:
      request_id:
        type: string
        description: Id of the request.
      status:
        type: string
        description: Status of the request.
        enum: [success, failed, running]
      gene_list_id:
        type: string
        description: Id of a gene list produced by successful completion this request.
      current_step:
        type: integer
        description: Current step of the transformation (optional).
      total_steps:
        type: integer
        description: Total number of steps in the transformation request (optional).
      error_msg:
        type: string
        description: Error message (for failed requests).
    required:
      - request_id
      - status
  error_msg:
    type: object
    properties:
      status:
        type: integer
      title:
        type: string
      detail:
        type: string
      type:
        type: string