gene_transformer_api.yml

swagger: '2.0'
info:
  title: API for gene-list transformers
  version: 1.3.0
  description: API for gene-list transformers.
host: sharpener.ncats.io
basePath: /<transformer-path>
schemes:
- "https"

paths:
  /transformer_info:
    get:
      tags:
      - transformer
      summary: Retrieve transformer info
      description: Provides information about the transformer.
      responses:
        200:
          description: successful operation
          schema:
            $ref: '#/definitions/transformer_info'

  /transform:
    post:
      tags:
      - transformer
      parameters:
      - in: body
        name: query
        description: Performs transformer query.
        required: true
        schema:
          $ref: '#/definitions/transformer_query'
      responses:
        200:
          description: successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/gene_info'
        400:
          description: bad request
          schema:
            $ref: '#/definitions/error_msg'
        500:
          description: internal server error
          schema:
            $ref: '#/definitions/error_msg'
        
definitions:

  transformer_query:
    type: object
    properties:
      genes:
        type: array
        items:
          $ref: '#/definitions/gene_info'
        description: >-
          List of genes that will be transformed. Required for expanders and filters;
          should be omitted 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: 
    - controls

  gene_info:
    type: object
    properties:
      gene_id:
        type: string
        description: Id of the gene.
      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.
      version:
        type: string
        description: Transformer's version.
      function:
        type: string
        description: Function of the transformer, one of 'producer', 'expander', 'filter'.
        enum: [producer, expander, filter]
      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
    - function
    - description
    - parameters
    - required_attributes


  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 paramater. 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

  error_msg:
    type: object
    properties:
      status:
        type: integer
      title:
        type: string
      detail:
        type: string
      type:
        type: string