ingest_openapi.yaml

openapi: 3.0.0
info:
  version: v1.0.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:
                  type: object
  /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:
                  type: object
    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
        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: object
    post:
      summary: Assign users to role
      description: Assign users to role
      operationId: ingest_operations.update_role
      requestBody:
        $ref: "#/components/requestBodies/RoleTypeRequest"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
  /site-role/{role_type}/email/{email}:
    parameters:
      - in: path
        name: role_type
        schema:
          type: string
        required: true
      - in: path
        name: email
        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: object
    delete:
      summary: Remove user from role
      description: Remove user from role
      operationId: ingest_operations.remove_user_from_role
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
        404:
          description: User not found in role
          content:
            application/json:
              schema:
                type: object
        405:
          description: Can't remove user from role
          content:
            application/json:
              schema:
                type: object
  /program:
    post:
      summary: Add authorization information for a new program
      description: Add authorization information for a new program
      operationId: ingest_operations.add_program_authorization
      requestBody:
        $ref: '#/components/requestBodies/ProgramAuthorizationRequest'
      responses:
          200:
            description: Success
            content:
              application/json:
                schema:
                  type: object
    get:
      summary: List registered programs
      description: List programs authorized on server
      operationId: ingest_operations.list_program_authorizations
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
  /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_authorization
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
    delete:
      description: Delete a program
      operationId: ingest_operations.remove_program
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
  /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
          content:
            application/json:
              schema:
                type: object
  /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: object
    post:
      summary: Approve pending users
      description: Approve bulk pending users for CanDIG access
      operationId: ingest_operations.approve_pending_users
      requestBody:
        $ref: '#/components/requestBodies/PendingUsersAuthorizationRequest'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
    delete:
      summary: Delete pending users
      description: Clear pending users for CanDIG access
      operationId: ingest_operations.clear_pending_users
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
  /user/pending/{user_id}:
    parameters:
      - in: path
        name: user_id
        schema:
          type: string
        required: true
    post:
      summary: Approve pending user
      description: Approve a pending user for CanDIG access
      operationId: ingest_operations.approve_pending_user
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
    delete:
      summary: Reject pending user
      description: Reject a pending user for CanDIG access
      operationId: ingest_operations.reject_pending_user
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
  /user/{user_id}/authorize:
    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 program authorizations
      description: List authorizations for programs for a user
      operationId: ingest_operations.list_programs_for_user
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
    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.authorize_program_for_user
      requestBody:
        $ref: '#/components/requestBodies/UserProgramAuthorizationRequest'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
  /user/{user_id}/authorize/{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 program authorization for a user
      description: Get authorization for a program for a user
      operationId: ingest_operations.get_program_for_user
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
    delete:
      summary: Remove a program authorization for a user
      description: Remove a program for a user
      operationId: ingest_operations.remove_program_for_user
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
  /genomic:
    post:
      summary: Ingest Genomic 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/GenomicIngestRequest'
      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: Success
          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
components:
  requestBodies:
    S3CredentialRequest:
      content:
        'application/json':
          schema:
            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
    GenomicIngestRequest:
      content:
        'application/json':
          schema:
            type: array
            items:
              $ref: "#/components/schemas/GenomicSample"
    ClinicalDonorRequest:
      content:
        'application/json':
          schema:
            $ref: "#/components/schemas/ClinicalDonor"
    ProgramAuthorizationRequest:
      content:
        'application/json':
          schema:
            $ref: "#/components/schemas/ProgramAuthorization"
    PendingUsersAuthorizationRequest:
      content:
        'application/json':
          schema:
            type: array
            items:
              type: string
    RoleTypeRequest:
      content:
        'application/json':
          schema:
            type: array
            items:
              type: string
    UserProgramAuthorizationRequest:
      content:
        'application/json':
          schema:
            $ref: "#/components/schemas/Program"
  schemas:
    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
    GenomicSample:
      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.
        genomic_file_id:
          type: string
          description: A unique name for this genomic data resource
          example: "HG00096.vcf"
        metadata:
          type: object
          description: Additional data that describes the genomic resource
          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
        - genomic_file_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
        genomic_file_sample_id:
          type: string
          description: the name of the sample in the genomic data resource
          example: TUMOUR/NORMAL/PROGRAM_SAMPLE_REGISTRATION_ID_1
      required:
        - submitter_sample_id
        - genomic_file_sample_id
    ProgramAuthorization:
      type: object
      description: Describes who is allowed to access 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
          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
    Program:
      type: object
      properties:
        program_id:
          type: string
        start_date:
          type: string
        end_date:
          type: string
      required:
        - program_id
        - start_date
        - end_date
    User:
      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
    PendingUsers:
      type: array
      description: a list of Users that are pending approval for access to this CanDIG node
      items:
        $ref: "#/components/schemas/User"
    UserProgramAuthorization:
      type: object
      description: describes an authorized user and the programs the user is authorized to view
      properties:
        user:
          $ref: "#/components/schemas/User"
        programs:
          type: array
          description: list of programs that this user is authorized to view
          items:
            $ref: "#/components/schemas/Program"
      required:
        - user
        - programs