Storage / Sample Open API Specification

openapi.yaml

openapi: 3.0.0
info:
  title: Workbench Instrument Integration API
  version: 1.0.0
  description: API for managing storage accounts and samples in the Omics Workbench

tags:
  - name: Storage
    description: Operations related to storage accounts
  - name: Samples
    description: Operations related to samples

paths:
  /{namespace}/storage:
    get:
      summary: List storage accounts
      operationId: listStorageAccounts
      tags:
        - Storage
      parameters:
        - $ref: '#/components/parameters/namespace'
        - $ref: '#/components/parameters/maxResults'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/sort'
        - in: query
          name: provider
          schema:
            $ref: '#/components/schemas/Provider'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorageAccountListResponse'
    post:
      summary: Add a new storage account
      operationId: addStorageAccount
      tags:
        - Storage
      parameters:
        - $ref: '#/components/parameters/namespace'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StorageAccount'
      responses:
        '201':
          description: Successfully added storage account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorageAccount'


  /{namespace}/storage/{storageId}:
    get:
      summary: Get a specific storage account
      operationId: getStorageAccount
      tags:
        - Storage
      parameters:
        - $ref: '#/components/parameters/namespace'
        - in: path
          name: storageId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved storage account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorageAccount'
        '404':
          description: Storage account not found
    put:
      summary: Update a specific storage account
      operationId: updateStorageAccount
      tags:
        - Storage
      parameters:
        - $ref: '#/components/parameters/namespace'
        - in: path
          name: storageId
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StorageAccount'
      responses:
        '200':
          description: Successfully retrieved storage account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorageAccount'
        '404':
          description: Storage account not found
    delete:
      summary: Delete a storage account
      operationId: deleteStorageAccount
      tags:
        - Storage
      parameters:
        - $ref: '#/components/parameters/namespace'
        - in: path
          name: storageId
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Successfully deleted storage account
        '404':
          description: Storage account not found
  /{namespace}/storage/platforms:
    get:
      summary: List platforms across all storage accounts
      operationId: listPlatforms
      tags:
        - Storage
      parameters:
        - $ref: '#/components/parameters/namespace'
        - $ref: '#/components/parameters/maxResults'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/sort'
        - in: query
          name: platform
          schema:
            $ref: '#/components/schemas/Platform'
        - in: query
          name: storageId
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformListResponse'
  /{namespace}/storage/{storageId}/platforms:
    post:
      summary: Create a platform
      operationId: platform
      tags:
        - Storage
      parameters:
        - $ref: '#/components/parameters/namespace'
        - $ref: '#/components/parameters/storageId'
      requestBody:
        required: true
        content: 
          application/json:
            schema:
              $ref: '#/components/schemas/Platform'

      responses:
        '201':
          description: Successfully Synced storage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Platform'
        '404':
          description: Storage account or sample not found

    get:
      summary: List platforms for a specific storage account
      operationId: listPlatformsInStorageAccount
      tags:
        - Storage
      parameters:
        - $ref: '#/components/parameters/namespace'
        - $ref: '#/components/parameters/storageId'
        - $ref: '#/components/parameters/maxResults'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/sort'
        - in: query
          name: platform
          schema:
            $ref: '#/components/schemas/Platform'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformListResponse'

  /{namespace}/storage/{storageId}/platforms/{platformId}:
    delete:
      summary: Delete platform
      operationId: deletePlatform
      tags:
        - Storage
      parameters:
        - $ref: '#/components/parameters/namespace'
        - $ref: '#/components/parameters/storageId'
        - $ref: '#/components/parameters/platformId'
      responses:
        '204':
          description: Successfully added storage
        '404':
          description: Storage not found
    get:
      summary: Delete platform
      operationId: getPlatform
      tags:
        - Storage
      parameters:
        - $ref: '#/components/parameters/namespace'
        - $ref: '#/components/parameters/storageId'
        - $ref: '#/components/parameters/platformId'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Platform'
        '404':
          description: Storage link not found
    put:
      summary: Delete platform
      operationId: updatePlatform
      tags:
        - Storage
      parameters:
        - $ref: '#/components/parameters/namespace'
        - $ref: '#/components/parameters/storageId'
        - $ref: '#/components/parameters/platformId'
      
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - path
              properties:
                path:
                  type: string
        
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Platform'
        '404':
          description: Storage link not found

  /{namespace}/samples:
    get:
      summary: List samples
      operationId: listSamples
      tags:
        - Samples
      parameters:
        - $ref: '#/components/parameters/namespace'
        - $ref: '#/components/parameters/maxResults'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/sort'
        - in: query
          name: platform
          schema:
            $ref: '#/components/schemas/Platform'
        - in: query
          name: storage
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SamplesListResponse'

  /{namespace}/samples/{sampleId}:
    get:
      summary: Describe a sample
      operationId: describeSample
      tags:
        - Samples
      parameters:
        - $ref: '#/components/parameters/namespace'
        - in: path
          name: sampleId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sample'
        '404':
          description: Sample not found

  /{namespace}/samples/{sampleId}/files:
    get:
      summary: List files for a sample
      operationId: listSampleFiles
      tags:
        - Samples
      parameters:
        - $ref: '#/components/parameters/namespace'
        - in: path
          name: sampleId
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/maxResults'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/sort'
        - in: query
          name: platform
          schema:
            $ref: '#/components/schemas/Platform'
        - in: query
          name: storage
          schema:
            type: string
        - in: query
          name: instrumentId
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SampleFile'
        '404':
          description: Sample not found

  /{namespace}/instruments:
    get:
      summary: List Instruments
      operationId: listInstruments
      tags:
        - Instruments
      parameters:
        - $ref: '#/components/parameters/namespace'
        - $ref: '#/components/parameters/maxResults'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/sort'
        - in: query
          name: platform
          schema:
            $ref: '#/components/schemas/Platform'
        - in: query
          name: storage
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstrumentListResponse'


components:
  parameters:
    namespace:
      in: path
      name: namespace
      required: true
      schema:
        type: string
      description: The namespace for the operation
    platformId:
      in: path
      name: platformId
      required: true
      schema:
        type: string
      description: the id of the platform
    storageId:
      in: path
      name: storageId
      required: true
      schema:
        type: string
      description: the id of the storage account
    maxResults:
      in: query
      name: maxResults
      schema:
        type: integer
    page:
      in: query
      name: page
      schema:
        type: integer
    pageSize:
      in: query
      name: pageSize
      schema:
        type: integer
    sort:
      in: query
      name: sort
      schema:
        type: string

  schemas:
    Pagination:
      type: object
      properties:
        next_page_url: 
          type: string
          format: uri
        total_elements:
          type: integer
          format: int32
    StorageAccountListResponse:
      type: object
      properties:
        accounts:
          type: array
          items:
            $ref: '#/components/schemas/StorageAccount'
        pagination:
          $ref: '#/components/schemas/Pagination'
    SamplesListResponse:
      type: object
      properties:
        samples:
          type: array
          items:
            $ref: '#/components/schemas/Sample'
        pagination:
          $ref: '#/components/schemas/Pagination'
    InstrumentListResponse:
      type: object
      properties:
        instruments:
          type: array
          items:
            $ref: '#/components/schemas/Instrument'
        pagination:
          $ref: '#/components/schemas/Pagination'
    PlatformListResponse:
      type: object
      properties:
        platforms:
          type: array
          items:
            $ref: '#/components/schemas/Platform'
        pagination:
          $ref: '#/components/schemas/Pagination'
  

    StorageAccount:
      type: object
      required:
        - name
        - provider
      properties:
        id:
          type: string
        namespace:
          type: string
        createdAt:
          type: string
          format: date-time
        lastUpdatedAt:
          type: string
          format: date-time
        name:
          type: string
        provider:
          $ref: '#/components/schemas/Provider'
        credentials:
          $ref: '#/components/schemas/StorageAccountCredentials'

    Instrument:
      type: object
      properties:
        id:
          type: string
        platformType:
          $ref: '#/components/schemas/PlatformType'
    StorageAccountCredentials:
      type: object
      properties:
        storageId:
          type: string
        createdAt:
          type: string
          format: date-time
        lastUpdatedAt:
          type: string
          format: date-time
        type:
          type: string

    Platform:
      type: object
      properties:
        id:
          type: string
        created_at:
          type: string
          format: datetime
        lastUdpatedAt:
          type: string
          format: datetime
        path:
          type: string
        name:
          type: string
        storageId:
          type: string
        namespace:
          type: string
        type:
          $ref: '#/components/schemas/PlatformType'

    PlatformType:
      type: string
      enum: [pacbio]

    Provider:
      type: string
      enum: [aws,gcp,azure]

    Sample:
      type: object
      properties:
        id:
          type: string
        namespace:
          type: string
        createdAt:
          type: string
          format: date-time
        lastUpdatedAt:
          type: string
          format: date-time
        files:
          type: array
          items:
            $ref: '#/components/schemas/SampleFile'

    SampleFile:
      type: object
      properties:
        sampleId:
          type: string
        namespace:
          type: string
        path:
          type: string
        storageSyncId:
          type: string
        instrumentId:
          type: string