openapi.yaml

# Genestack Uploader
# A HTTP server providing an API and a frontend for easy uploading to Genestack

# Copyright (C) 2021, 2022 Genome Research Limited

# Author: Michael Grace <mg38@sanger.ac.uk>

# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.

# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.

# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <https://www.gnu.org/licenses/>.

openapi: 3.0.1
info:
  title: Genestack Uploader
  description: This is the API documentation for the HGI Genestack Uploader app
  version: ""
servers:
  - url: https://apps.hgi.sanger.ac.uk/genestack-uploader/api
  - url: "http://localhost:5000/api"
  - url: "http://172.27.17.238/genestack-uploader/api"
paths:
  /:
    get:
      summary: Get basic information about the server
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Status"
  /studies:
    get:
      tags:
        - studies
      summary: Get information about all studies
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AllStudies"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        500:
          $ref: "#/components/responses/500"
      security:
        - GenestackAPIToken: []
    post:
      tags:
        - studies
      summary: Start a job to add a new study to Genestack
      requestBody:
        description: The body contains all the data we need to create the study, including the samples file, any columns getting renamed and the rest of the metadata.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewStudy"
        required: true
      responses:
        202:
          $ref: "#/components/responses/202"
        401:
          $ref: "#/components/responses/401"
      security:
        - GenestackAPIToken: []

  /studies/{studyAccession}:
    get:
      tags:
        - studies
      summary: "Get data from a particular study"
      parameters:
        - name: studyAccession
          in: path
          description: Genestack Study Accession
          required: true
          schema:
            type: string
      responses:
        200:
          description: study found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StudyFound"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        404:
          $ref: "#/components/responses/404"
        500:
          $ref: "#/components/responses/500"
      security:
        - GenestackAPIToken: []

  /studies/{studyAccession}/signals:
    get:
      tags:
        - studies
      summary: Get all the signals associated to the study
      parameters:
        - name: studyAccession
          in: path
          description: Genestack Study Accession
          required: true
          schema:
            type: string
      responses:
        200:
          description: Study found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AllSignals"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        404:
          $ref: "#/components/responses/404"
        500:
          $ref: "#/components/responses/500"
      security:
        - GenestackAPIToken: []

    post:
      tags:
        - studies
      summary: Submit a job to add a new signal to Genestack
      parameters:
        - name: studyAccession
          in: path
          description: Genestack Study Accession
          required: true
          schema:
            type: string
      requestBody:
        description: The body contains all the data we need to create the signal, including the data file, signal type, tag, linking attributes and metadata.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewSignal"
        required: true
      responses:
        202:
          $ref: "#/components/responses/202"
        401:
          $ref: "#/components/responses/401"
      security:
        - GenestackAPIToken: []

  /studies/{studyAccession}/signals/{signalAccession}:
    get:
      tags:
        - studies
      summary: Get the metadata for a particular signal
      parameters:
        - name: studyAccession
          in: path
          description: Genestack Study Accession
          required: true
          schema:
            type: string
        - name: signalAccession
          in: path
          description: Genestack Signal Accession
          required: true
          schema:
            type: string
      responses:
        200:
          description: Signal Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SignalFound"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        404:
          $ref: "#/components/responses/404"
        500:
          $ref: "#/components/responses/500"
      security:
        - GenestackAPIToken: []

  /templates:
    get:
      tags:
        - templates
      summary: Gets all the templates from Genestack
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AllTemplates"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        500:
          $ref: "#/components/responses/500"
      security:
        - GenestackAPIToken: []

  /templates/{templateAccession}:
    get:
      tags:
        - templates
      summary: Gets the details about the particular template
      parameters:
        - name: templateAccession
          in: path
          description: Genestack Template Accession
          required: true
          schema:
            type: string
      responses:
        200:
          description: Template Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Template"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        404:
          $ref: "#/components/responses/404"
        500:
          $ref: "#/components/responses/500"
      security:
        - GenestackAPIToken: []

  /templateTypes:
    get:
      tags:
        - templates
      summary: Gets the display names and datatypes for templates
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AllTemplateTypes"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        500:
          $ref: "#/components/responses/500"
      security:
        - GenestackAPIToken: []

  /jobs/{id}:
    get:
      tags:
        - jobs
      parameters:
        - name: id
          in: path
          description: Job ID
          required: true
          schema:
            type: string
      summary: Get the information about a particular job
      responses:
        200:
          description: Job Found
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/JobQueued"
                  - $ref: "#/components/schemas/JobRunning"
                  - $ref: "#/components/schemas/JobFinished"

components:
  schemas:
    Status:
      type: object
      properties:
        status:
          type: string
          default: OK
        data:
          type: object
          properties:
            version:
              type: string
              description: version number of the app's software
              example: "1.0"
            server:
              type: string
              description: genestack server the app is connected to
              example: https://genestack.sanger.ac.uk
            package:
              type: string
              description: version number of the uploadtogenestack package
              example: "1.0"

    JobSubmitted:
      type: object
      properties:
        status:
          type: string
          example: OK
        data:
          type: object
          properties:
            jobId:
              type: string
              example: "ABCDE-12345-HIJKL-67890-MNOPQ"

    Study:
      type: object
      properties:
        genestack:accession:
          type: string
          example: GSF123456
      additionalProperties:
        type: string

    AllStudies:
      type: object
      properties:
        status:
          type: string
          default: OK
        data:
          type: array
          items:
            $ref: "#/components/schemas/Study"

    NewStudy:
      type: object
      properties:
        Study Source:
          type: string
          example: IBD
        Sample File:
          type: string
          description: location on the S3 bucket associated to the currently in use Genestack server
          example: uploadDirectory/samples.tsv
        addedColumns:
          type: array
          description: allow a new sample file to be generated with additional columns, containing this column title and value
          items:
            type: object
            properties:
              title:
                type: string
                description: the name you want to give the column
                example: year
              value:
                type: string
                description: the value you want in the cells of the column
                example: 2022
        renamedColumns:
          type: array
          description: allow a new sample file to be generated with renamed columns
          items:
            type: object
            properties:
              old:
                type: string
                description: the current name of the column
                example: col0
              new:
                type: string
                description: the name you want to give the column
                example: col1
        deletedColumns:
          type: array
          description: column titles of columns in sample file you want deleted
          items:
            type: string
            description: column titles
            example: col0
        template:
          type: string
          description: the genestack accession of the template in use
          example: GSF123456
      additionalProperties:
        type: string

    StudyCreated:
      type: object
      properties:
        studyAccession:
          type: string
          example: GSF123456

    StudyFound:
      type: object
      properties:
        status:
          type: string
          default: OK
        data:
          $ref: "#/components/schemas/Study"

    Signal:
      type: object
      additionalProperties:
        type: string

    AllSignals:
      type: object
      properties:
        status:
          type: string
          default: OK
        data:
          type: object
          properties:
            studyAccession:
              type: string
              example: GSF123456
            signals:
              type: array
              items:
                $ref: "#/components/schemas/Signal"

    NewSignal:
      type: object
      properties:
        type:
          type: string
          description: the type of signal being created
          enum:
            - expression
            - variant
        data:
          type: string
          description: location on the S3 bucket associated to the currently in use Genestack server
          example: uploadDirectory/expressions.gct
        tag:
          type: string
          example: exp1
        linkingattribute:
          type: array
          description: the fields you want to link using. typically, you'll want to use `Study Source ID`
          items:
            type: string
            example: Sample Source ID
        metadata:
          type: object
          additionalProperties:
            type: string
        generateMinimalVCF:
          type: boolean
          description: Whether to generate a minimal VCF file. This only applies if `type` is "Variant".

    SignalCreated:
      type: object
      properties:
        signal:
          type: string
          default: "created"
        studyAccession:
          description: the accession of the study the signal was linked to
          type: string
          example: GSF123456

    SignalFound:
      type: object
      properties:
        status:
          type: string
          default: OK
        data:
          type: object
          properties:
            studyAccession:
              type: string
              example: "GSF123456"
            signal:
              $ref: "#/components/schemas/Signal"

    Template:
      type: object
      properties:
        status:
          type: string
          default: OK
        data:
          type: object
          properties:
            accession:
              type: string
              description: Genestack accession of the template
              example: GSF123456
            template:
              type: object
              additionalProperties:
                type: object

    AllTemplates:
      type: object
      properties:
        status:
          type: string
          default: OK
        data:
          type: array
          items:
            type: object
            additionalProperties:
              type: object

    AllTemplateTypes:
      type: object
      properties:
        status:
          type: string
          default: OK
        data:
          type: array
          items:
            type: object
            properties:
              canAdd:
                type: boolean
              dataType:
                type: string
                description: an awkward name from genestack
              displayName:
                type: string
                description: a user friendly name
              fileClassName:
                type: string
                description: an awkward name from genestack

    InvalidRequest:
      type: object
      properties:
        error:
          type: string
          default: bad request
        name:
          type: string
          example: LinkingNotPossibleError
        detail:
          type: array
          items:
            type: object

    InvalidBody:
      type: object
      properties:
        error:
          type: string
          default: no valid json body

    MissingToken:
      type: object
      properties:
        status:
          type: string
          default: FAIL
        data:
          type: object
          properties:
            error:
              type: string
              default: missing token

    JobReturnsForbidden:
      type: object
      properties:
        error:
          type: string
          default: forbidden

    Forbidden:
      type: object
      properties:
        status:
          type: string
          default: FAIL
        data:
          type: object
          properties:
            error:
              type: string
              default: forbidden

    S3PermissionDenied:
      type: object
      properties:
        error:
          type: string
          default: S3 bucket permission denied

    JobReturnsNotFound:
      type: object
      properties:
        error:
          type: string
          default: "not found"
        name:
          type: string
          example: StudyNotFoundError
        detail:
            type: array
            items:
                type: object
    
    NotFound:
      type: object
      properties:
        status:
          type: string
          default: FAIL
        data:
          type: object
          properties:
            error:
              type: string
              default: "not found"
            name:
              type: string
              example: StudyNotFoundError
            detail:
                type: array
                items:
                    type: object

    JobReturnsOtherError:
      type: object
      properties:
        error:
          type: string
          default: internal server error
        name:
          type: string
          example: GenestackUploadError
        detail:
          type: array
          items:
            type: object

    InternalServerError:
      type: object
      properties:
        status:
          type: string
          default: FAIL
        data:
          type: object
          properties:
            error:
              type: string
              default: internal server error
            name:
              type: string
              example: GenestackUploadError
            detail:
              type: array
              items:
                type: object

    JobQueued:
      type: object
      properties:
        status:
          type: string
          default: OK
        data:
          type: object
          properties:
            status:
              type: string
              default: QUEUED

    JobRunning:
      type: object
      properties:
        status:
          type: string
          default: OK
        data:
          type: object
          properties:
            status:
              type: string
              default: RUNNING
            startTime:
              type: string
              example: "2022-01-26T16:00:00.000000"

    JobFinished:
      type: object
      properties:
        status:
          type: string
          default: OK
        data:
          type: object
          properties:
            status:
              type: string
              oneOf:
                - COMPLETED
                - FAILED
            startTime:
              type: string
              example: "2022-01-26T16:00:00.000000"
            endTime:
              type: string
              example: "2022-01-26T17:00:00.000000"
            output:
              type: object
              oneOf:
                - $ref: "#/components/schemas/InvalidRequest"
                - $ref: "#/components/schemas/InvalidBody"
                - $ref: "#/components/schemas/StudyCreated"
                - $ref: "#/components/schemas/SignalCreated"
                - $ref: "#/components/schemas/S3PermissionDenied"
                - $ref: "#/components/schemas/JobReturnsNotFound"
                - $ref: "#/components/schemas/JobReturnsOtherError"
                - $ref: "#/components/schemas/JobReturnsForbidden"

  responses:
    202:
      description: job submitted
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/JobSubmitted"

    401:
      description: missing token
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/MissingToken"

    403:
      description: forbidden
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Forbidden"

    404:
      description: not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/NotFound"

    500:
      description: error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/InternalServerError"

  securitySchemes:
    GenestackAPIToken:
      type: apiKey
      name: Genestack-API-Token
      in: header