ingest_openapi.yaml

openapi: 3.0.0
info:
  version: v1.1.0
  title: 'CanDIGv2 Ingest Service'
  description: 'API for ingesting data into the CanDIG stack'
paths:
  /service-info:
    get:
      summary: Retrieve information about this service
      description: Returns information about the ingest service
      operationId: ingest_operations.get_service_info
      responses:
        200:
          description: Retrieve info about the ingest service
          content:
            application/json:
              schema:
                type: object
  /s3-credential:
    post:
      summary: Add credentials for an S3 bucket
      description: Add credentials for an S3 bucket
      operationId: ingest_operations.add_s3_credential
      requestBody:
        $ref: '#/components/requestBodies/S3CredentialRequest'
      responses:
          200:
            description: Success
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/S3Credential'
  /s3-credential/endpoint/{endpoint_id}/bucket/{bucket_id}:
    parameters:
      - in: path
        name: endpoint_id
        schema:
          type: string
        required: true
      - in: path
        name: bucket_id
        schema:
          type: string
        required: true
    get:
      summary: get credentials for an S3 bucket
      description: get credentials for an S3 bucket
      operationId: ingest_operations.get_s3_credential
      responses:
          200:
            description: Success
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/S3Credential"
    delete:
      summary: delete credentials for an S3 bucket
      description: delete credentials for an S3 bucket
      operationId: ingest_operations.delete_s3_credential
      responses:
          200:
            description: Success
            content:
              application/json:
                schema:
                  type: object

  /site-role/{role_type}:
    parameters:
      - in: path
        name: role_type
        description: Defined site roles for this CanDIG node. By default, admin and curator are defined.
        schema:
          type: string
        required: true
    get:
      summary: List users in role_type
      description: List users in role_type
      operationId: ingest_operations.list_role
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
  /site-role/{role_type}/user_id/{user_id}:
    parameters:
      - in: path
        name: role_type
        description: Defined site roles for this CanDIG node. By default, admin and curator are defined.
        schema:
          type: string
        required: true
      - in: path
        name: user_id
        schema:
          type: string
        required: true
    get:
      summary: Is user in this role?
      description: Is user in this role?
      operationId: ingest_operations.is_user_in_role
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: boolean
    post:
      summary: Assign user to role
      description: Assign user to role
      operationId: ingest_operations.add_user_to_role
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
    delete:
      summary: Remove user from role
      description: Remove user from role
      operationId: ingest_operations.remove_user_from_role
      responses:
        200:
          description: Success
        404:
          description: User not found in role
        405:
          description: Can't remove user from role
  /program:
    post:
      summary: Add authorization information for a new program
      description: Add authorization information for a new program
      operationId: ingest_operations.add_program
      requestBody:
        $ref: '#/components/requestBodies/ProgramIngestRequest'
      responses:
          200:
            description: Success
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/Program"
    get:
      summary: List registered programs
      description: List programs authorized on server
      operationId: ingest_operations.list_programs
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Program"
  /program/{program_id}:
    parameters:
      - in: path
        name: program_id
        schema:
          type: string
        required: true
    get:
      summary: Get authorization information for a program
      description: Get authorization information for a program
      operationId: ingest_operations.get_program
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Program"
    delete:
      description: Delete a program
      operationId: ingest_operations.remove_program
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Program"
  /user/pending/request:
    post:
      summary: Add pending user
      description: Add the user specified in the Bearer jwt to the pending users list
      operationId: ingest_operations.add_pending_user
      responses:
        200:
          description: Success
  /user/pending:
    get:
      summary: List pending users
      description: List pending users for authorization
      operationId: ingest_operations.list_pending_users
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/UserInfo"
    post:
      summary: Approve pending users
      description: Approve bulk pending users for CanDIG access
      operationId: ingest_operations.approve_pending_users
      requestBody:
        $ref: '#/components/requestBodies/ApprovePendingUserRequest'
      responses:
        200:
          description: Success
    delete:
      summary: Delete pending users
      description: Clear pending users for CanDIG access
      operationId: ingest_operations.clear_pending_users
      responses:
        200:
          description: Success
  /user/pending/{user_id}:
    parameters:
      - in: path
        name: user_id
        schema:
          type: string
        required: true
        description: The user ID to check. If "me", return information about the requesting user
    get:
      summary: Is a user pending?
      description: Is a user pending?
      operationId: ingest_operations.is_user_pending
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: boolean
    post:
      summary: Approve pending user
      description: Approve a pending user for CanDIG access
      operationId: ingest_operations.approve_pending_user
      responses:
        200:
          description: Success
    delete:
      summary: Reject pending user
      description: Reject a pending user for CanDIG access
      operationId: ingest_operations.reject_pending_user
      responses:
        200:
          description: Success
  /user/preapproved:
    get:
      summary: List preapproved users
      description: List preapproved users for authorization
      operationId: ingest_operations.list_preapproved_users
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/UserInfo"
    post:
      summary: Add preapproved users
      description: Add bulk preapproved users for CanDIG access
      operationId: ingest_operations.add_preapproved_users
      requestBody:
        $ref: '#/components/requestBodies/AddPreapprovedUserRequest'
      responses:
        200:
          description: Success
    delete:
      summary: Delete preapproved users
      description: Clear preapproved users for CanDIG access
      operationId: ingest_operations.clear_preapproved_users
      responses:
        200:
          description: Success
  /user/preapproved/{user_id}:
    parameters:
      - in: path
        name: user_id
        schema:
          type: string
        required: true
    get:
      summary: Check preapproved list for user
      description: Check preapproved list for user
      operationId: ingest_operations.get_preapproved_user
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserInfo"
        404:
          description: User not found
    post:
      summary: Add preapproved user
      description: Add a preapproved user for CanDIG access
      operationId: ingest_operations.add_preapproved_user
      responses:
        200:
          description: Success
    delete:
      summary: Remove preapproved user
      description: Remove a preapproved user for CanDIG access
      operationId: ingest_operations.remove_preapproved_user
      responses:
        200:
          description: Success
  /user/{user_id}:
    parameters:
      - in: path
        name: user_id
        schema:
          type: string
        required: true
        description: The user ID to check. If "me", return information about the requesting user
    get:
      summary: List authorization information about a user
      description: List authorization information about a user
      operationId: ingest_operations.list_authz_for_user
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserAuthorization"
        403:
          description: User not found
    delete:
      summary: Revoke CanDIG authorization for a user
      description: Revoke CanDIG authorization for a user
      operationId: ingest_operations.revoke_authz_for_user
      responses:
        200:
          description: Success
  /user/{user_id}/dac_authorization:
    parameters:
      - in: path
        name: user_id
        schema:
          type: string
        required: true
    post:
      summary: Authorize a program for a user
      description: Authorize a program for a user (or update a program auth for a user)
      operationId: ingest_operations.add_dac_authz_for_user
      requestBody:
        $ref: '#/components/requestBodies/DACAuthorizationRequest'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserAuthorization'
  /user/{user_id}/dac_authorization/{program_id}:
    parameters:
      - in: path
        name: user_id
        schema:
          type: string
        required: true
      - in: path
        name: program_id
        schema:
          type: string
        required: true
    get:
      summary: Get a DAC authorization for a user
      description: Remove a DAC authorization for a user
      operationId: ingest_operations.get_dac_authz_for_user
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DACAuthorization"
    delete:
      summary: Remove a DAC authorization for a user
      description: Remove a DAC authorization for a user
      operationId: ingest_operations.remove_dac_authz_for_user
      responses:
        200:
          description: Success
  /genomic:
    post:
      summary: Ingest Analysis data
      description: Add linkages between clinical donors and genomic data.
      operationId: ingest_operations.add_genomic_linkages
      parameters:
        - name: do_not_index
          in: query
          required: false
          schema:
            type: boolean
          description: set to true to prevent indexing of genomic files
      requestBody:
        $ref: '#/components/requestBodies/AnalysisIngestRequest'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IngestResponse"
  /clinical:
    post:
      summary: Ingest Clinical data
      description: Add a list of donors with clinical data produced by the clinical ETL.
      operationId: ingest_operations.add_clinical_donors
      parameters:
        - name: batch_size
          in: query
          required: false
          schema:
            type: integer
          description: Number of items to be processed in one batch
      requestBody:
        $ref: "#/components/requestBodies/ClinicalDonorRequest"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IngestResponse"
  /status/{queue_id}:
    parameters:
      - in: path
        name: queue_id
        schema:
          type: string
        required: true
    get:
      summary: Check status of ingest
      description: Return status of ingest operation
      operationId: ingest_operations.get_ingest_status
      responses:
        200:
          description: Ingest in progress
          content:
            application/json:
              schema:
                type: object
        201:
          description: Ingest completed
          content:
            application/json:
              schema:
                type: object
  /get-token:
    get:
      summary: Get a new token
      description: Exchange the refresh token implicit in the request for a new one
      operationId: ingest_operations.get_token
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
components:
  requestBodies:
    S3CredentialRequest:
      content:
        'application/json':
          schema:
            $ref: "#/components/schemas/S3Credential"
    AnalysisIngestRequest:
      content:
        'application/json':
          schema:
            type: array
            items:
              $ref: "#/components/schemas/AnalysisSample"
    ClinicalDonorRequest:
      content:
        'application/json':
          schema:
            $ref: "#/components/schemas/ClinicalDonor"
    ProgramIngestRequest:
      content:
        'application/json':
          schema:
            $ref: "#/components/schemas/Program"
    ApprovePendingUserRequest:
      content:
        'application/json':
          schema:
            type: array
            items:
              type: string
    AddPreapprovedUserRequest:
      content:
        'application/json':
          schema:
            type: array
            items:
              type: string
    RoleTypeRequest:
      content:
        'application/json':
          schema:
            type: array
            items:
              type: string
    DACAuthorizationRequest:
      content:
        'application/json':
          schema:
            $ref: "#/components/schemas/DACAuthorization"
  schemas:
    S3Credential:
      type: object
      properties:
        endpoint:
          type: string
          description: URL to the endpoint
          pattern: (https*):\/\/(.+)
          example: http://candig.docker.internal:9000
        bucket:
          type: string
          description: name of the bucket
        access_key:
          type: string
          description: access key for the bucket
        secret_key:
          type: string
          description: secret key for the bucket
      required:
        - endpoint
        - bucket
        - access_key
        - secret_key
    ClinicalDonor:
      type: object
      properties:
        openapi_url:
          type: string
          description: URL of schema used to generate this mapping
        donors:
          type: array
          items:
            type: object
            description: A DonorWithClinicalData object, as specified in the schema in openapi_url
        katsu_sha:
          type: string
          description: the SHA of the version of Katsu used to generate the schema.
        statistics:
          $ref: "#/components/schemas/Statistics"
    Statistics:
      type: object
      properties:
        required_but_missing:
          type: object
          description: for each schema, a count of required fields that are present vs missing
        schemas_used:
          type: array
          description: a list of schemas used in this dataset
          items:
            type: string
        cases_missing_data:
          type: array
          description: a list of cases that have missing data
          items:
            type: string
        schemas_not_used:
          type: array
          description: a list of schemas that are never used in this dataset
          items:
            type: string
        summary_cases:
          type: object
          description: overall completeness counts
          properties:
            complete_cases:
              type: integer
              description: how many cases have complete data
            total_cases:
              type: integer
              description: how many cases are in this dataset
    IngestResponse:
      type: object
      properties:
        queue_id:
          type: string
          description: Queue ID to get status of ingest
        warnings:
          type: array
          items:
            type: string
    AnalysisSample:
      type: object
      properties:
        program_id:
          type: string
          description: Name of the program this sample belongs to. The user must be authorized to add data to this program.
        analysis_id:
          type: string
          description: A unique name for this downstream analysis
          example: "HG00096.vcf"
        metadata:
          type: object
          description: Additional data that describes the downstream analysis
          properties:
            sequence_type:
              type: string
              description: type of data sequenced (whole genome or whole transcriptome)
              enum:
                - wgs
                - wts
              default: wgs
            data_type:
              type: string
              description: type of data represented in the resource (variant or read)
              enum:
                - variant
                - read
            reference:
              type: string
              description: which reference genome was used for alignment (hg37 or hg38)
              enum:
                - hg37
                - hg38
              default: hg38
          required:
            - sequence_type
            - data_type
            - reference
        main:
          $ref: "#/components/schemas/File"
        index:
          $ref: "#/components/schemas/File"
        samples:
          type: array
          description: An array of links between donor data (e.g. MoH Sample Registrations) and the samples in the genomic data resource
          items:
            $ref: "#/components/schemas/SampleLink"
      required:
        - program_id
        - analysis_id
        - metadata
        - main
        - index
        - samples
    File:
      type: object
      description: Object describing a file
      properties:
        name:
          type: string
          description: name of the file, including all extensions
        access_method:
          type: string
          description: fully-described URI to the file
          oneOf:
            - $ref: "#/components/schemas/S3Access"
            - $ref: "#/components/schemas/FileAccess"
      required:
        - name
        - access_method
    FileAccess:
      type: string
      description: an absolute path to a local file on the HTSGet server itself, expressed as a file URI
      pattern: file:\/\/\/(.+)
      example: file:///data/samples/HG00096.vcf.gz
    S3Access:
      type: string
      description: |
        a description of an S3 URI. NB: even though the s3 prefix is incorrect, we allow it in parsing so that we can give better feedback to the user if a url is provided in that form.
      pattern: (https*|s3):\/\/(.+)\/(.+)\/(.+)
      example: http://s3.us-east-1.amazonaws.com/1000genomes/HG00096.vcf.gz
    SampleLink:
      type: object
      description: Link between donor data (e.g. MoH Sample Registrations) and the samples in the genomic data resource
      properties:
        submitter_sample_id:
          type: string
          description: the name of the sample as listed in the linked donor data
          example: sample_registration_id_1
        analysis_sample_id:
          type: string
          description: the name of the sample in the analysis
          example: TUMOUR/NORMAL/PROGRAM_SAMPLE_REGISTRATION_ID_1
      required:
        - submitter_sample_id
        - analysis_sample_id
    Program:
      type: object
      description: Describes a program
      properties:
        program_id:
          type: string
          description: name of the program
        program_curators:
          type: array
          description: list of users who are program curators for this program
          items:
            type: string
        team_members:
          type: array
          description: list of users who are original researchers for this program
          items:
            type: string
        creation_date:
          type: string
          pattern: '^\d{4}-\d{2}-\d{2}$'
          description: date program was created, for embargo purposes. This may or may not be the date of ingest.
      required:
        - program_id
        - program_curators
        - team_members
    DACAuthorization:
      type: object
      properties:
        program_id:
          type: string
        start_date:
          type: string
          pattern: '^\d{4}-\d{2}-\d{2}$'
        end_date:
          type: string
          pattern: '^\d{4}-\d{2}-\d{2}$'
      required:
        - program_id
        - start_date
        - end_date
    UserInfo:
      type: object
      description: describes an authenticated user
      properties:
        sample_jwt:
          type: string
          description: a sample jwt for this user from their IDP
        user_name:
          type: string
          description: unique id of user, from CANDIG_USER_KEY field
      required:
        - user_name
    UserAuthorization:
      type: object
      description: describes an authorized user and the programs the user is authorized to view
      properties:
        userinfo:
          $ref: "#/components/schemas/UserInfo"
        site_roles:
          type: array
          items:
            type: string
        program_authorizations:
          type: object
          properties:
            team_member:
              type: array
              description: list of programs that the user is a team member of
              items:
                type: string
            program_curator:
              type: array
              description: list of programs that the user is a curator of
              items:
                type: string
            dac_authorizations:
              type: array
              description: list of programs that this user is authorized to view
              items:
                $ref: "#/components/schemas/DACAuthorization"