APISpecification.yaml

openapi: 3.0.0
info:
  title: Tools api
  version: 0.0.1
paths:
  /api/tools/vep/config:
    get:
      parameters:
        - name: genome_id
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VepConfigResponse'
  /api/tools/vep/submissions:
    post:
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                genome_id:
                  type: string
                input_file:
                  type: string
                  format: binary
                parameters:
                  type: string
                  description: |
                    Stringified JSON of parameters, such as '{"transcript_set":"blah","symbol":true,"biotype":true}'
      responses:
        '200':
          description: Successful operaiton.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VepFormSubmissionCreatedResponse'
  /api/tools/vep/submissions/{id}/status:
    get:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VepSubmissionStatusResponse'
        '404':
          description: Submission not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VepSubmissionNotFoundResponse'
  /api/tools/vep/submissions/{id}/results:
    get:
      description: Returns results of VEP analysis
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          required: false
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: Successful operaiton.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VepResultsResponse'
components:
  schemas:
    AlternativeVariantAllele:
      type: object
      required:
        - allele_sequence
        - allele_type
        - predicted_molecular_consequences
      properties:
        allele_sequence:
          type: string
        allele_type:
          type: string
        representative_population_allele_frequency:
          type: number
          nullable: true
        predicted_molecular_consequences:
          type: array
          items:
            anyOf:
              - $ref: '#/components/schemas/PredictedTranscriptConsequence'
              - $ref: '#/components/schemas/PredictedIntergenicConsequence'
    BooleanConfigOption:
      type: object
      required:
        - label
        - description
        - type
        - default_value
      properties:
        label:
          type: string
        description:
          type: string
          nullable: true
        type:
          type: string
          enum:
            - boolean
        default_value:
          type: boolean
    PaginationMetadata:
      type: object
      required:
        - page
        - per_page
        - total
      properties:
        page:
          type: integer
        per_page:
          type: integer
        total:
          type: integer
    PredictedIntergenicConsequence:
      type: object
      required:
        - feature_type
        - consequences
      properties:
        feature_type:
          nullable: true
          description: The value of this field is always null. The presence of null in this field will serve as a marker that this is a consequence of an intergenic variant.
        consequences:
          type: array
          items:
            type: string
          description: The only expected member of this array will be the string 'intergenic_variant'
    PredictedTranscriptConsequence:
      type: object
      required:
        - feature_type
        - stable_id
        - gene_stable_id
        - gene_symbol
        - biotype
        - is_canonical
        - consequences
        - strand
      properties:
        feature_type:
          type: string
          enum:
            - transcript
        stable_id:
          type: string
          description: transcript stable id, versioned
        gene_stable_id:
          type: string
          description: gene stable id, versioned
        gene_symbol:
          type: string
          nullable: true
        biotype:
          type: string
        is_canonical:
          type: boolean
        consequences:
          type: array
          items:
            type: string
        strand:
          type: string
          enum:
            - forward
            - reverse
    ReferenceVariantAllele:
      type: object
      required:
        - allele_sequence
      properties:
        allele_sequence:
          type: string
    SelectConfigOption:
      type: object
      required:
        - label
        - description
        - type
        - options
        - default_value
      properties:
        label:
          type: string
        description:
          type: string
          nullable: true
        type:
          type: string
          enum:
            - select
        options:
          type: array
          items:
            type: object
            properties:
              label:
                type: string
              value:
                type: string
            required:
              - label
              - value
        default_value:
          type: string
    Variant:
      type: object
      required:
        - name
        - allele_type
        - location
        - reference_allele
        - alternative_alleles
      properties:
        name:
          type: string
          nullable: true
          description: User's name for the variant; optional
        allele_type:
          type: string
        location:
          type: object
          properties:
            region_name:
              type: string
            start:
              type: integer
            end:
              type: integer
          required:
            - region_name
            - start
            - end
        reference_allele:
          $ref: '#/components/schemas/ReferenceVariantAllele'
        alternative_alleles:
          type: array
          items:
            $ref: '#/components/schemas/AlternativeVariantAllele'
    VepConfigResponse:
      type: object
      required:
        - parameters
      properties:
        parameters:
          type: array
          items:
            anyOf:
              - $ref: '#/components/schemas/BooleanConfigOption'
              - $ref: '#/components/schemas/SelectConfigOption'
    VepResultsResponse:
      type: object
      required:
        - metadata
        - variants
      properties:
        metadata:
          type: object
          properties:
            pagination:
              $ref: '#/components/schemas/PaginationMetadata'
          required:
            - pagination
        variants:
          type: array
          items:
            $ref: '#/components/schemas/Variant'
    VepSubmissionNotFoundResponse:
      type: object
      required:
        - details
        - status_code
      properties:
        status_code:
          type: integer
          default: 404
        details:
          type: string
          example: A submission with id 1234567 was not found
    VepSubmissionStatusResponse:
      type: object
      required:
        - submission_id
        - status
      properties:
        submission_id:
          type: string
        status:
          type: string
          description: >
            The possible statuses for a VEP submission are based on the list of documented statuses of Seqera workflows
            (see https://github.com/seqeralabs/tower-cli/blob/50dd04dd806acf8461dfc9b286faec7e874aec15/USAGE.md?plain=1#L254-L259),
            except for the 'UNKNOWN' status, which is listed in Seqera docs without explanation how a workflow can get into that status.
            If the tools api receives the 'UNKNOWN' status from the Seqera platform, the status reported to the client is FAILED.
          enum:
            - SUBMITTED
            - RUNNING
            - SUCCEEDED
            - FAILED
            - CANCELLED
    VepFormSubmissionCreatedResponse:
      type: object
      required:
        - submission_id
      properties:
        submission_id:
          type: string