user-workspaces-spec.yaml

openapi: 3.0.0
info:
  description: The User Workspaces Server is an HTTP/Websocket server which allows developers to create workspaces and launch interactive sessions on a variety of resources.
  version: 1.0.5
  title: HuBMAP User Workspaces Server
  termsOfService: 'https://hubmapconsortium.org'
  contact:
    name: HuBMAP Help Desk
    email: help@hubmapconsortium.org
  license:
    name: MIT License
    url: 'https://github.com/hubmapconsortium/user_workspaces_server/blob/master/license.txt'
servers:
  - url: "https://workspaces.api.hubmapconsortium.org/"
components:
  schemas:
    WorkspaceRequest:
      type: object
      properties:
        workspace_name:
          type: string
        description:
          type: string
        default_job_type:
          type: string
          example: jupyter_lab
        workspace_details:
          type: object
          properties:
            globus_groups_token:
              type: string
              description: Only used when specifying HubmapLocalFileSystemStorage
            symlinks:
              type: array
              items:
                properties:
                  name:
                    type: string
                  path:
                    type: string
                  dataset_uuid:
                    type: string
                    description: Only used when specifying HubmapLocalFileSystemStorage
            files:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  content:
                    type: string
    WorkspaceJobStartRequest:
      type: object
      properties:
        job_type:
          type: string
          description: This should be the id index of one of the JobType entries
          example: 'jupyter_lab'
        job_details:
          type: object
        resource_options:
          type: object
          properties:
            num_cpus:
              type: integer
              description: Number of CPUs to request
            memory_mb:
              type: integer
              description: Amount of memory to request in megabytes.
            time_limit_minutes:
              type: integer
              description: Amount of requested time for job, in minutes.
            gpu_enabled:
              type: boolean
              description: Whether the user is requesting gpu support or not.
    WorkspaceDataResponse:
      type: object
      properties:
        id:
          type: integer
        description:
          type: string
        disk_space:
          type: integer
        datetime_created:
          type: string
        status:
          type: string
          enum:
            - idle
            - active
            - deleting
            - error
        default_job_type:
            type: string
        workspace_details:
          type: object
          properties:
            request_workspace_details:
              type: object
            current_workspace_details:
              type: object
    GetWorkspacesResponse:
      type: object
      properties:
        message:
          type: string
        success:
          type: boolean
        workspaces:
          type: array
          items:
            $ref: '#/components/schemas/WorkspaceDataResponse'
    PostWorkspaceResponse:
      type: object
      properties:
        message:
          type: string
        success:
          type: boolean
        workspace:
          $ref: '#/components/schemas/WorkspaceDataResponse'
    StartWorkspaceResponse:
      type: object
      properties:
        message:
          type: string
        success:
          type: boolean
        data:
          type: object
          properties:
            job:
              $ref: '#/components/schemas/JobDataResponse'
    JobDataResponse:
      type: object
      properties:
        id:
          type: integer
        workspace_id:
          type: integer
        resource_job_id:
          type: integer
        job_type:
          type: string
        status:
          type: string
          enum:
            - running
            - pending
            - complete
            - failed
            - stopping
        datetime_created:
          type: string
        datetime_start:
          type: string
        datetime_end:
          type: string
        core_hours:
          type: integer
        job_details:
          type: object
          properties:
            request_job_details:
              type: object
            current_job_details:
              type: object
    GetJobResponse:
      type: object
      properties:
        message:
          type: string
        success:
          type: boolean
        data:
          type: object
          properties:
            jobs:
              type: array
              items:
                $ref: '#/components/schemas/JobDataResponse'
    JobTypeResponse:
      type: object
      properties:
        job_type_id:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
    GeneralResponse:
      type: object
      properties:
        message:
          type: string
        success:
          type: boolean
paths:
  '/workspaces/':
    get:
      tags:
        - Workspaces
      summary: Get a list of workspaces associated with the user.
      parameters:
        - in: query
          name: name
          schema:
            type: string
          description: Name of workspace
        - in: query
          name: description
          schema:
            type: string
          description: Description of workspace
        - in: query
          name: status
          schema:
            type: string
            enum:
              - idle
              - active
              - deleting
              - error
          description: Workspace status
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetWorkspacesResponse'
    post:
      tags:
        - Workspaces
      summary: Create a new workspace.
      requestBody:
        description: Workspace to create in the system.
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/WorkspaceRequest'
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PostWorkspaceResponse'
  '/workspaces/{workspace_id}/':
    get:
      tags:
        - Workspaces
      summary: Get a specific workspace.
      parameters:
        - name: workspace_id
          in: path
          description: Identifier for workspace.
          required: true
          schema:
             type: string
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetWorkspacesResponse'
    put:
      tags:
        - Workspaces
      summary: Update a workspace.
      parameters:
        - name: workspace_id
          in: path
          description: Identifier for workspace.
          required: true
          schema:
             type: string
      requestBody:
        description: Workspace to create in the system.
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/WorkspaceRequest'
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralResponse'
    delete:
      tags:
        - Workspaces
      summary: Delete a specific workspace.
      parameters:
        - name: workspace_id
          in: path
          description: Identifier for workspace.
          required: true
          schema:
             type: string
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralResponse'
  '/workspaces/{workspace_id}/upload/':
    put:
      tags:
        - Workspaces
      summary: Upload files to a workspace.
      parameters:
        - name: workspace_id
          in: path
          description: Identifier for workspace.
          required: true
          schema:
             type: string
      requestBody:
        description: If using the upload PUT type, include the files you wish to upload here.
        content:
          'multipart/form-data':
            schema:
              type: object
              properties:
                filename:
                  type: array
                  items:
                    type: string
                    format: binary
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralResponse'
  '/workspaces/{workspace_id}/start/':
    put:
      tags:
        - Workspaces
      summary: Start a job for a workspace.
      parameters:
        - name: workspace_id
          in: path
          description: Identifier for workspace.
          required: true
          schema:
             type: string
      requestBody:
        description: Job details.
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/WorkspaceJobStartRequest'
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartWorkspaceResponse'
  '/jobs/':
    get:
      tags:
        - Jobs
      summary: Get a list of jobs associated with the user.
      parameters:
        - in: query
          name: workspace_id
          schema:
            type: integer
          description: ID of parent workspace.
        - in: query
          name: resource_job_id
          schema:
            type: integer
          description: Resource's ID for this job.
        - in: query
          name: job_type
          schema:
            type: string
          description: This should be the id index of one of the JobType entries.
        - in: query
          name: status
          schema:
            type: string
            enum:
              - running
              - pending
              - complete
              - failed
              - stopping
          description: Status of job.
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetJobResponse'
  '/jobs/{job_id}/':
    get:
      tags:
        - Jobs
      summary: Get a specific job.
      parameters:
        - name: job_id
          in: path
          description: Identifier for job.
          required: true
          schema:
             type: string
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetJobResponse'
  '/jobs/{job_id}/stop/':
    put:
      tags:
        - Jobs
      summary: Stop a running job.
      parameters:
        - name: job_id
          in: path
          description: Identifier for job.
          required: true
          schema:
             type: string
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralResponse'
  '/job_types/':
    get:
      tags:
        - JobTypes
      summary: Get the job types that can be run.
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobTypeResponse'
tags:
  - name: Workspaces
  - name: Jobs
  - name: JobTypes