ingest-api-spec.yaml

openapi: 3.0.0
info:
  description: |
    A restful web service exposing calls needed for the Ingest UI React application.
  version: 2.0.20
  title: HuBMAP Ingest API
  contact:
    name: HuBMAP Help Desk
    email: help@hubmapconsortium.org
  license:
    name: MIT License
    url: 'https://github.com/hubmapconsortium/ingest-api/blob/main/license.txt'
tags:
  - name: dataset
    description: Operations pertaining to datasets
    externalDocs:
      description: Find out more about our dataset
      url: "http://hubmapconsortium.org"
  - name: collection
    description: Operations for a collection
    externalDocs:
      description: Find out more about our entities
      url: "http://hubmapconsortium.org"
  - name: specimen
    description: Operations for specimens
    externalDocs:
      description: Find out more about our entities
      url: "http://hubmapconsortium.org"
paths:
  /datasets:
    get:
      tags:
        - dataset
      summary: Get a list of HuBMAP datasets filtered by optional parameters.  If no parameters are set, the call returns a list of datasets filtered by the user's token permissions
      operationId: searchDataset
      parameters:
        - name: group
          in: query
          description: 'The name of a HuBMAP group (All Groups, IEC Testing Group, Stanford TMC, Vanderbilt TMC, University of Florida TMC, California Institute of Technology TMC, University of California San Diego TMC)'
          required: false
          schema:
            type: string
        - name: keywords
          in: query
          description: 'One or more keywords to use for searching the free text associated with the datasets.'
          required: false
          schema:
            type: string
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                properties:
                  datasets:
                    type: array
                    items:
                      $ref: '#/components/schemas/Dataset'
        "400":
          description: The user sent a bad parameter (e.g. a nonexistent group name) or there was a system error
        "401":
          description: User's token is not valid
    post:
      tags:
        - dataset
      summary: Creates a new HuBMAP dataset.
      operationId: addDataset
      responses:
        "201":
          description: successful created
        "400":
          description: missing data that is required to create a new dataset or a system error occurred
        "401":
          description: User is not authorized to create datasets or user's group information cannot be determined
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Dataset"
          application/xml:
            schema:
              $ref: "#/components/schemas/Dataset"
        description: Dataset object that needs to be created
        required: true
  /datasets/data-status:
    get:
      summary: Get the datasets data status
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                properties:
                  data:
                    type: object
                  last_updated:
                    type: integer
        "400":
          description: There was a system error
  "/datasets/{identifier}":
    get:
      tags:
        - dataset
      summary: Get a single HuBMAP dataset by id
      operationId: getDataset
      parameters:
        - name: identifier
          in: path
          description: The unique identifier of dataset.  this identifier can be a UUID, Display DOI (HBM365.KSBD.575) or DOI (365KSBD575).
          required: true
          schema:
            type: string
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                properties:
                  dataset:
                    $ref: "#/components/schemas/Dataset"
        "400":
          description: Missing dataset identifier or identifier cannot be found
        "401":
          description: User's token is not valid
    put:
      tags:
        - dataset
      summary: Modify a single HuBMAP dataset by id
      operationId: putDataset
      parameters:
        - name: identifier
          in: path
          description: The unique identifier of dataset.  this identifier can be a UUID, Display DOI (HBM365.KSBD.575) or DOI (365KSBD575).
          required: true
          schema:
            type: string
      responses:
        "204":
          description: successful operation
        "400":
          description: Missing dataset Identifier or the data for the update
        "401":
          description: User is not authorized to modify datasets
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Dataset"
        description: Updated dataset object
        required: true
  "/datasets/{identifier}/metadata-json":
    put:
      tags:
        - dataset
      summary: Modify a single HuBMAP dataset identifier by adding or updating the metadata.json file
      operationId: datasetsMetadataJson
      parameters:
        - name: identifier
          in: path
          description: Dataset identifier which is a UUID without the dashes
          required: true
          schema:
            type: string
      responses:
        "201":
          description: metadata.json file created
        "400":
          description: Missing or improper dataset identifier
        "401":
          description: User is not authorized to access endpoint
        "403":
          description: User must be a member of the HuBMAP Data Admin group
        '500':
          description: Internal error
  /datasets/bulk/submit:
    put:
      tags:
        - datasets
      summary: "Submit a list of Datasets for processing. This requires Data-Admin privileges."
      requestBody:
        content:
          application/json:
            schema:
                type: array
                items:
                  $ref: '#/components/schemas/entity_uuid'
      responses:
        "202":
          description: The Datasets were successfully submitted for processing
        "401":
          description: The user did not supply a valid token
        "403":
          description: The user does not have Data-Admin privileges
        "404":
          description: One or more supplied datasets do not exist
        "500":
          description: An unexpected error occurred
  "/specimens/{identifier}":
    get:
      tags:
        - specimen
      summary: Get a single specimen by identifier
      operationId: getSpecimen
      parameters:
        - name: identifier
          in: path
          description: The unique identifier of specimen.  this identifier can be a UUID, Display DOI (HBM365.KSBD.575) or DOI (365KSBD575).
          required: true
          schema:
            type: string
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                properties:
                  specimen:
                    $ref: "#/components/schemas/Specimen"
        "400":
          description: Missing specimen identifier or identifier cannot be found or a system error
        "401":
          description: User's token is not valid
  /file-upload:
    post:
      summary: "Upload a file to temporarily stage.  On success the file will be staged and a temporary id will be returned to reference the staged file by.  The temporary id can be used by the *_files_to_add properties during PUT/POST for Donors and Samples to commit the file permanantly and associate with an entity." 
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: The file was successfully uploaded and staged, the temporary file id is returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  temp_file_id:
                    type: string
        '400':
          description: Missing file
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to upload the file.
        '500':
          description: Internal error
  /file-commit:
    post:
      summary: "File commit triggered by entity-api trigger method for Donor/Sample/Dataset. Donor: image files. Sample: image files and metadata files. Dataset: only the one thumbnail file. This call also creates the symbolic from the file uuid dir under uploads assets dir so the uploaded files can be exposed via gateway's file assets service" 
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                temp_file_id:
                  type: string
                entity_uuid:
                  type: string
                user_token:
                  type: string
      responses:
        '200':
          description: The file was successfully commited, the file uuid is returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  filename:
                    type: string
                  file_uuid:
                    type: string
        '400':
          description: Missing JSON input
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '500':
          description: Internal error
  /file-remove:
    post:
      summary: "File removal triggered by entity-api trigger method for Donor and Sample during entity update. Donor/Sample/Dataset. Donor: image files. Sample: image files and metadata files. Dataset: only the one thumbnail file." 
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                entity_uuid:
                  type: string
                file_uuids:
                  type: array
                  items:
                    $ref: '#/components/schemas/file_uuid'
                files_info_list:
                  type: array
                  items:
                    $ref: '#/components/schemas/file_info'
                  
      responses:
        '200':
          description: The file was successfully deleted.
        '400':
          description: Missing JSON input
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '500':
          description: Internal error
  /donors/bulk-upload:
    post:
      summary: "Upload a tsv file containing multiple donor records to temporary stage. On success the file will be staged and a temporary id will be returned to reference the staged file by. Each record in the tsv are validated to verify that they are acceptable values for a donor and all necessary fields are included. Temporary id is only provided if all donor records in the tsv are valid."
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: File uploaded, temp directory and temp_id created.
          content:
            application/json:
              schema:
                properties:
                  temp_id:
                    type: string
                    example: abcdefghij0123456789
        '400':
          description: File not upload failed or file contains invalid donors
          content:
            application/json:
              schema:
                properties:
                  status:
                    type: string
                  message:
                    type: string
        '401':
          description: The user's token has expired or the user did not have authorization
        '500':
          description: Internal error
  /donors/bulk:
    post:
      summary: "Confirm that you want to create donors from the previously uploaded tsv file. Donors are validated once more and then if valid, new donors are created via the entity api"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                temp_id:
                  type: string
                  example: abcdefghij0123456789
                group_uuid:
                  type: string
                  example: a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6
      responses:
        '200':
          description: The samples in the tsv file were successfully created.
          content:
            application/json:
              schema:
                properties:
                  status:
                    type: string
                  data:
                    type: object
                    properties:
                      entity_response:
                        type: object
                        properties:
                          specimen:
                            $ref: '#/components/schemas/Specimen'

        '400':
          description: File not found for given temp_id
          content:
            application/json:
              schema:
                properties:
                  status:
                    type: string
                  message:
                    type: string
        '401':
          description: The user's token has expired or the user did not have authorization
        '500':
          description: Internal error
  /samples/bulk-upload:
    post:
      summary: "Upload a tsv file containing multiple donor records to temporary stage. On success the file will be staged and a temporary id will be returned to reference the staged file by. Each record in the tsv are validated to verify that they are acceptable values for a donor and all necessary fields are included. Temporary id is only provided if all donor records in the tsv are valid."
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: File uploaded, temp directory and temp_id created.
          content:
            application/json:
              schema:
                properties:
                  temp_id:
                    type: string
                    example: abcdefghij0123456789
        '400':
          description: File not upload failed or file contains invalid donors
          content:
            application/json:
              schema:
                properties:
                  status:
                    type: string
                  message:
                    type: string
  /samples/bulk:
    post:
      summary: "Confirm that you want to create donors from the previously uploaded tsv file. Donors are validated once more and then if valid, new donors are created via the entity api"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                temp_id:
                  type: string
                  example: abcdefghij0123456789
                group_uuid:
                  type: string
                  example: a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6
      responses:
        '200':
          description: The samples in the tsv file were successfully created.
          content:
            application/json:
              schema:
                properties:
                  status:
                    type: string
                  data:
                    type: object
                    properties:
                      entity_response:
                        type: object
                        properties:
                          specimen:
                            $ref: '#/components/schemas/Specimen'
        '400':
          description: File not found for given temp_id
          content:
            application/json:
              schema:
                properties:
                  status:
                    type: string
                  message:
                    type: string
        '401':
          description: The user's token has expired or the user did not have authorization
        '500':
          description: Internal error

  /uploads/data-status:
    get:
      summary: Get the uploads data status
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                properties:
                  data:
                    type: object
                  last_updated:
                    type: integer
        "400":
          description: There was a system error

  /uploads/{identifier}/validate:
    put:
      tags:
        - specimen
      summary: Validate an upload.
      operationId: validateUpload
      parameters:
        - name: identifier
          in: path
          description: The unique identifier of Upload.  this identifier needs to be a valid HuBMAP UUID.
          required: true
          schema:
            type: string
      responses:
        "200":
          description: successful operation
        "400":
          description: There was a system error or an error in the data submitted
        "401":
          description: User's token is not valid
        "500":
          description: An unexpected error occured

  /uploads/{identifier}/reorganize:
    put:
      tags:
        - specimen
      summary: Reorganize an upload. Creates Datasets from the Upload
      operationId: reorganizeUpload
      parameters:
        - name: identifier
          in: path
          description: The unique identifier of Upload.  this identifier needs to be a valid HuBMAP UUID.
          required: true
          schema:
            type: string
      responses:
        "200":
          description: successful operation
        "400":
          description: There was a system error or an error in the data submitted
        "401":
          description: User's token is not valid
        "500":
          description: An unexpected error occured

  /metadata/validate:
    post:
      summary: "Validate uploaded tsv file"
      requestBody:
        description: Metadata information to be validated
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/metadata_validate'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/metadata_validate'
      responses:
        '200':
          description: The tsv file was successfully validated.
        '400':
          description: Missing input
        '406':
          description: The tsv file was not acceptable
        '500':
          description: Internal error

  /privs/has-data-admin:
    get:
      summary: Determine if the user has data admin privs
      operationId: privs_has_data_admin_privs
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                properties:
                  has_data_admin_privs:
                    type: boolean
        "401":
          description: User's token is not valid or not specified

servers:
  - url: "https://uuid.hubmapconsortium.org/dataingest"
  - url: "http://uuid.hubmapconsortium.org/dataingest"
components:
  securitySchemes:
    globus_auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: "https://auth.globus.org/v2/oauth2/authorize"
          scopes:
            "write:dataset": modify datasets
            "read:dataset": read datasets
    api_key:
      type: apiKey
      name: api_key
      in: header
  schemas:
    file_info:
      type: object
      required:
        - filename
        - file_uuid
      properties:
        filename:
          type: string
        file_uuid:
          type: string
    file_uuid:
      type: string
    entity_uuid:
      type: string
      pattern: '^[a-f0-9]{32}$'
    Dataset:
      type: object
      required:
        - uuid
        - doi
        - display_doi
        - status
        - entity_type
      properties:
        uuid:
          type: string
          example: 6dba271c5c0bbd09f8b73784c2c40f95
        doi:
          type: string
          example: 569SKTF599
        display_doi:
          type: string
          example: HBM569.SKTF.599
        status:
          type: string
        entity_type:
          type: string
          example: Dataset
        collection:
          $ref: "#/components/schemas/Collection"
        phi:
          type: boolean
          example: false
      xml:
        name: DataSet
    Collection:
      type: object
      required:
        - uuid
        - doi
        - display_doi
        - label
        - entity_type
      properties:
        uuid:
          type: string
          example: a23526eaa92beef971cd013b5c4a1ce5
        doi:
          type: string
          example: 527RQJT662
        display_doi:
          type: string
          example: HBM527.RQJT.662
        label:
          type: string
          example: Test Collection 1
        entity_type:
          type: string
          example: Collection
        description:
          type: string
          example: THis is a description of Collection 1
      xml:
        name: Collection
    Specimen:
      type: object
      required:
        - uuid
        - doi
        - display_doi
        - entity_type
      properties:
        uuid:
          type: string
          example: a23526eaa92beef971cd013b5c4a1ce5
        doi:
          type: string
          example: 527RQJT662
        display_doi:
          type: string
          example: HBM527.RQJT.662
        entity_type:
          type: string
          example: Sample, Donor
      xml:
        name: Specimen
    metadata_validate:
      type: object
      required:
        - entity_type
        - validate_uuids
      properties:
        pathname:
          type: string
        entity_type:
          type: string
        sub_type:
          type: string
        validate_uuids:
          type: string
        tsv_row:
          type: string