OpenAPI Specification

Github gist

Open in Swagger

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

** For discussion around the platform and defining what workflows are automatically linked to samples.

Platform:

The key identifier which stems from the sample data files. This will be the link necessary for us to identify and list the available workflows in both the CLI and UI.