openapi.yml

openapi: 3.0.3
info:
  title: Terra Scientific Pipelines Service
  version: 1.0.0
paths:
  # Admin APIs
  /api/admin/v1/pipeline/{pipelineName}:
    parameters:
      - $ref: '#/components/parameters/PipelineName'
    get:
      summary: Get description for a given pipeline.
      tags: [ admin ]
      operationId: getPipeline
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminPipeline'
        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/PermissionDenied'
        500:
          $ref: '#/components/responses/ServerError'
    patch:
      summary: Update attributes for a given pipeline.
      tags: [ admin ]
      operationId: updatePipeline
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePipelineRequestBody'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminPipeline'
        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/PermissionDenied'
        500:
          $ref: '#/components/responses/ServerError'

  # Pipeline related APIs
  /api/pipelines/v1:
    get:
      summary: Return all available Pipelines
      operationId: getPipelines
      tags: [ pipelines ]
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPipelinesResult'
        500:
          $ref: '#/components/responses/ServerError'

  /api/pipelines/v1/{pipelineName}:
    parameters:
      - $ref: '#/components/parameters/PipelineName'
    get:
      summary: Return info about the specified pipeline
      operationId: getPipelineDetails
      tags: [ pipelines ]
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PipelineWithDetails'
        400:
          $ref: '#/components/responses/BadRequest'
        500:
          $ref: '#/components/responses/ServerError'

  # pipeline run related APIs
  /api/pipelineruns/v1/{pipelineName}/prepare:
    parameters:
      - $ref: '#/components/parameters/PipelineName'
    post:
      summary: Prepare a new pipeline run
      operationId: preparePipelineRun
      tags: [ pipelineRuns ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreparePipelineRunRequestBody'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreparePipelineRunResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/ServerError'

  /api/pipelineruns/v1/{pipelineName}/start:
    parameters:
      - $ref: '#/components/parameters/PipelineName'
    post:
      summary: Start a prepared pipeline run
      operationId: startPipelineRun
      tags: [ pipelineRuns ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartPipelineRunRequestBody'
      responses:
        200:
          description: PipelineRun is complete (succeeded or failed)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncPipelineRunResponse'
        202:
          description: PipelineRun is running
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncPipelineRunResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/PermissionDenied'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/ServerError'

  /api/pipelineruns/v1/{pipelineName}/result/{jobId}:
    parameters:
      - $ref: '#/components/parameters/PipelineName'
      - $ref: '#/components/parameters/JobId'
    get:
      summary: Retrieve result for a specified pipeline run
      operationId: getPipelineRunResult
      tags: [ pipelineRuns ]
      responses:
        200:
          description: PipelineRun is complete (succeeded or failed)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncPipelineRunResponse'
        202:
          description: PipelineRun is running
          headers:
            Retry-After:
              description: >-
                optional - estimated seconds to wait before polling again. This allows a server to offer a hint as to when the job might be complete.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncPipelineRunResponse'
        400:
          description: Bad request - invalid id, id not for a createPipelineRunRequest job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
        403:
          description: No permission to see job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
        404:
          description: Not found - job id does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
        500:
          $ref: '#/components/responses/ServerError'

  /api/pipelineruns/v1/pipelineruns:
    get:
      tags: [ pipelineRuns ]
      summary: Return a paginated list of all pipeline runs the caller has access to
      operationId: getAllPipelineRuns
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/PageToken'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPipelineRunsResponse'
        500:
          $ref: '#/components/responses/ServerError'

  # quota related APIs
  /api/quotas/v1/{pipelineName}:
    parameters:
      - $ref: '#/components/parameters/PipelineName'
    get:
      summary: Return info about the user's quota usage for the specified pipeline
      operationId: getQuotaForPipeline
      tags: [ quotas ]
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuotaWithDetails'
        400:
          $ref: '#/components/responses/BadRequest'
        500:
          $ref: '#/components/responses/ServerError'

  # Stairway job related APIs go here
  /api/job/v1/jobs:
    get:
      tags: [ jobs ]
      summary: Return a list of all jobs the caller has access to
      operationId: getAllJobs
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/PageToken'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetJobsResponse'
        500:
          $ref: '#/components/responses/ServerError'

  /api/job/v1/jobs/{jobId}:
    parameters:
      - $ref: '#/components/parameters/JobId'
    get:
      summary: Retrieve a specified job
      tags: [ jobs ]
      operationId: getJob
      responses:
        200:
          description: Job is complete (succeeded or failed)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobReport'
        202:
          description: Job is running
          headers:
            Retry-After:
              description: >-
                optional - estimated seconds to wait before polling again. This allows
                a server to offer a hint as to when the job might be complete.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobReport'
        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/PermissionDenied'
        404:
          $ref: '#/components/responses/NotFound'

  # Public APIs
  /status:
    get:
      summary: Check status of the service.
      tags: [ public ]
      operationId: getStatus
      security: [ ]
      responses:
        200:
          description: OK
        500:
          $ref: '#/components/responses/ServerError'
        503:
          $ref: '#/components/responses/SystemStatusResponse'

  /version:
    get:
      summary: Get version info of the deployed service.
      tags: [ public ]
      operationId: getVersion
      security: [ ]
      responses:
        200:
          description: Version information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionProperties'
        404:
          description: "Version not configured"
        500:
          $ref: '#/components/responses/ServerError'

components:
  parameters:
    JobId:
      name: jobId
      in: path
      description: A UUID identifier for a pipelines job
      required: true
      schema:
        type: string
        format: uuid

    Limit:
      name: limit
      in: query
      description: The maximum number of items to return. Default 10
      required: false
      schema:
        type: integer
        minimum: 1
        default: 10

    PageToken:
      name: pageToken
      in: query
      description: A previously returned page token describing where to resume an enumeration.
      required: false
      schema:
        type: string

    PipelineName:
      name: pipelineName
      in: path
      description: A string identifier to used to identify a pipeline in the service.
      required: true
      schema:
        type: string

    WorkspaceId:
      name: workspaceId
      in: path
      description: A UUID identifier for a workspace job
      required: true
      schema:
        type: string
        format: uuid

  responses:
    # Error Responses
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorReport'
    PermissionDenied:
      description: Permission denied
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorReport'
    NotFound:
      description: Not found (or unauthorized)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorReport'
    ServerError:
      description: Server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorReport'
    SystemStatusResponse:
      description: A JSON description of the subsystems and their statuses.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SystemStatus'
    JobResultResponse:
      description: Result of a job (failed or succeeded)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobResult'

  schemas:
    # Terra common schemas
    ErrorReport:
      type: object
      required: [ message, statusCode, causes ]
      properties:
        message:
          type: string
        statusCode:
          type: integer
        causes:
          type: array
          items:
            type: string

    VersionProperties:
      type: object
      properties:
        gitTag:
          type: string
        gitHash:
          type: string
        github:
          type: string
        build:
          type: string

    SystemStatus:
      required: [ ok, systems ]
      type: object
      properties:
        ok:
          type: boolean
          description: whether any system(s) need attention
        systems:
          type: object
          additionalProperties:
            type: object
            properties:
              ok:
                type: boolean
              messages:
                type: array
                items:
                  type: string

    # Async API schemas
    JobReport:
      type: object
      required: [ id, status, statusCode, resultURL ]
      properties:
        id:
          description: caller-provided unique identifier for the job
          type: string
        description:
          description: caller-provided description of the job
          type: string
        status:
          description: status of the job
          type: string
          enum: [ 'RUNNING', 'SUCCEEDED', 'FAILED' ]
        statusCode:
          description: HTTP code providing status of the job.
          type: integer
        submitted:
          description: timestamp when the job was submitted; in ISO-8601 format
          type: string
        completed:
          description: >-
            timestamp when the job completed - in ISO-8601 format. Present if
            status is SUCCEEDED or FAILED.
          type: string
        resultURL:
          description: >-
            URL where the result of the job can be retrieved. Equivalent to a
            Location header in HTTP.
          type: string

    JobControl:
      type: object
      required: [ id ]
      properties:
        id:
          $ref: '#/components/schemas/Id'
        # In the future, notification configuration will also be part of JobControl.

    JobResult:
      type: object
      description: |
        The result of a call that triggers an asynchronous job.
      required: [ jobReport ]
      properties:
        jobReport:
          $ref: '#/components/schemas/JobReport'
        errorReport:
          $ref: '#/components/schemas/ErrorReport'

    # Special schema that gets overridden during Swagger generation, for compatibility with the Python client;
    # This gets around the issue of Python interpreting `object` as `dict` and instead makes it map to Python `Any`
    AnyTypeMapsToJavaObject: {}

    # Teaspoons schemas; please keep alphabetized
    AdminPipeline:
      description: |
        Object containing the pipeline identifier, display name, description, and control workspace information for a Pipeline.
      type: object
      required: [ pipelineName, displayName, description, workspaceBillingProject, workspaceName, workspaceStorageContainerName, workspaceGoogleProject, wdlMethodVersion ]
      properties:
        pipelineName:
          $ref: "#/components/schemas/PipelineName"
        displayName:
          $ref: "#/components/schemas/PipelineDisplayName"
        description:
          $ref: "#/components/schemas/PipelineDescription"
        wdlMethodVersion:
          $ref: "#/components/schemas/PipelineWdlMethodVersion"
        workspaceBillingProject:
          $ref: "#/components/schemas/PipelineWorkspaceBillingProject"
        workspaceName:
          $ref: "#/components/schemas/PipelineWorkspaceName"
        workspaceStorageContainerName:
          $ref: "#/components/schemas/PipelineWorkspaceStorageContainerName"
        workspaceGoogleProject:
          $ref: "#/components/schemas/PipelineWorkspaceGoogleProject"

    AsyncPipelineRunResponse:
      description: Result of an asynchronous pipeline run request.
      type: object
      required: [ jobReport, pipelineRunReport ]
      properties:
        jobReport:
          $ref: '#/components/schemas/JobReport'
        errorReport:
          $ref: '#/components/schemas/ErrorReport'
        pipelineRunReport:
          $ref: '#/components/schemas/PipelineRunReport'

    StartPipelineRunRequestBody:
      description: |
        Object containing the user-provided information defining a pipeline run request.
      type: object
      required: [ jobControl ]
      properties:
        description:
          description: >-
            User-provided description of the pipeline run.
          type: string
        jobControl:
          $ref: "#/components/schemas/JobControl"

    GetJobsResponse:
      description: result of a getJobs request
      type: object
      properties:
        totalResults:
          type: integer
        pageToken:
          type: string
        results:
          description: List of retrieved jobs
          type: array
          items:
            $ref: '#/components/schemas/JobReport'

    GetPipelinesResult:
      description: result of a getPipelines request
      type: object
      properties:
        results:
          description: List of retrieved pipelines
          type: array
          items:
            $ref: '#/components/schemas/Pipeline'

    GetPipelineRunsResponse:
      type: object
      properties:
        pageToken:
          type: string
        results:
          description: List of pipeline runs
          type: array
          items:
            $ref: '#/components/schemas/PipelineRun'

    Id:
      description: |
        Required unique identifier (UUID) for a job.
      type: string
      format: uuid

    JobStatus:
      description: |
        The current status of the job.
      type: string
      format: string

    JobTimeCompleted:
      description: |
        The time the job was completed.
      type: string
      format: string

    JobTimeSubmitted:
      description: |
        The time the job was submitted.
      type: string
      format: string

    Pipeline:
      description: |
        Object containing the pipeline identifier, display name, and description of a Pipeline.
      type: object
      required: [ pipelineName, displayName, description ]
      properties:
        pipelineName:
          $ref: "#/components/schemas/PipelineName"
        displayName:
          $ref: "#/components/schemas/PipelineDisplayName"
        description:
          $ref: "#/components/schemas/PipelineDescription"

    PipelineDescription:
      description: |
        The description for the Pipeline.
      type: string
      format: string

    PipelineDisplayName:
      description: |
        The display name for the Pipeline.
      type: string
      format: string

    PipelineInputIsRequired:
      description: |
        Whether the input field is required.
      type: boolean
      format: boolean

    PipelineInputName:
      description: |
        The name of the input field.
      type: string
      format: string

    PipelineInputType:
        description: |
            The type of the input field.
        type: string
        format: string

    PipelineName:
      description: |
        The identifier string for the Pipeline.
      type: string
      format: string

    PipelineRun:
      description: |
        Object containing the job id, status, and user-provided description of a Pipeline Run.
      type: object
      required: [ pipelineName, displayName, description ]
      properties:
        jobId:
          $ref: '#/components/schemas/Id'
        status:
          $ref: "#/components/schemas/PipelineRunStatus"
        description:
          $ref: "#/components/schemas/PipelineRunDescription"

    PipelineRunDescription:
      description: |
        The user-provided description for the pipeline run.
      type: string
      format: string

    PipelineRunReport:
      description: |
        Object containing metadata about the pipeline that was run, as well as pipeline run outputs if the run has completed successfully.
      type: object
      required: [ pipelineName, pipelineVersion, wdlMethodVersion ]
      properties:
        pipelineName:
          $ref: "#/components/schemas/PipelineName"
        pipelineVersion:
          $ref: "#/components/schemas/PipelineVersion"
        wdlMethodVersion:
          $ref: "#/components/schemas/PipelineWdlMethodVersion"
        outputs:
          $ref: "#/components/schemas/PipelineRunOutputs"

    PipelineRunStatus:
      description: |
        The current status of the pipeline run.
      type: string
      format: string

    PipelineRunOutputs:
      description: |
        The output(s) of a successful pipeline run.
      type: object
      additionalProperties:
        $ref: "#/components/schemas/AnyTypeMapsToJavaObject"

    PipelineType:
      description: |
          The general type of the Pipeline.
      type: string
      format: string

    PipelineUserProvidedInputDefinition:
      description: |
        User-provided input fields and specifications for the Pipeline.
      type: object
      properties:
        name:
          $ref: "#/components/schemas/PipelineInputName"
        type:
          $ref: "#/components/schemas/PipelineInputType"
        isRequired:
          $ref: "#/components/schemas/PipelineInputIsRequired"

    PipelineUserProvidedInputDefinitions:
      description: |
        A list of user-provided input fields and specifications for the Pipeline.
      type: array
      items:
        $ref: "#/components/schemas/PipelineUserProvidedInputDefinition"

    PipelineUserProvidedInputs:
      description: |
        A map(string:object) of user-provided inputs for the Pipeline.
      type: object
      additionalProperties:
        $ref: "#/components/schemas/AnyTypeMapsToJavaObject"

    PipelineVersion:
      description: |
        An identifier Integer for the Pipeline Version.
      type: integer

    PipelineWdlMethodVersion:
      description: |
        An identifier string for the Pipeline Wdl Version i.e. github repo tag/branch/release
      type: string

    PipelineWorkspaceGoogleProject:
      description: |
        The google project of the workspace to run the pipeline in.
      type: string
      format: string

    PipelineWorkspaceId:
      description: |
        The uuid for the workspace to run the pipeline in.
      type: string
      format: uuid

    PipelineWorkspaceName:
      description: |
        The name of the workspace to run the pipeline in.
      type: string
      format: string

    PipelineWorkspaceBillingProject:
      description: |
        The Terra billing project of the workspace to run the pipeline in.
      type: string
      format: string

    PipelineWorkspaceStorageContainerName:
      description: |
          The name of the workspace storage container (e.g. google bucket name, without gs:// prefix).
      type: string
      format: string

    PipelineWithDetails:
      description: |
        Object containing the pipeline identifier, display name, description, type, and required inputs of a Pipeline.
      type: object
      required: [ pipelineName, displayName, description, type, inputs ]
      properties:
        pipelineName:
          $ref: "#/components/schemas/PipelineName"
        displayName:
          $ref: "#/components/schemas/PipelineDisplayName"
        description:
          $ref: "#/components/schemas/PipelineDescription"
        type:
          $ref: "#/components/schemas/PipelineType"
        inputs:
          $ref: "#/components/schemas/PipelineUserProvidedInputDefinitions"

    PreparePipelineRunRequestBody:
      description: |
        Object containing the user-provided information defining a pipeline run request.
      type: object
      required: [ jobId, pipelineVersion, pipelineInputs ]
      properties:
        jobId:
          $ref: '#/components/schemas/Id'
        pipelineVersion:
          $ref: "#/components/schemas/PipelineVersion"
        pipelineInputs:
          $ref: "#/components/schemas/PipelineUserProvidedInputs"

    PreparePipelineRunResponse:
        description: Result of the preparePipelineRun request, containing signed URLs to upload input files
        type: object
        properties:
            jobId:
              $ref: '#/components/schemas/Id'
            fileInputUploadUrls:
              type: object
              additionalProperties:
                type: object
                additionalProperties:
                  type: string

    QuotaConsumed:
      description: |
        Quota consumed by the user
      type: integer

    QuotaLimit:
      description: |
        Maximum allowable quota for the pipeline
      type: integer

    QuotaWithDetails:
      description: |
        Object containing the pipeline identifier, quota limit, and quota usage of a Pipeline.
      type: object
      required: [ pipelineName, quotaLimit, quotaConsumed ]
      properties:
        pipelineName:
          $ref: "#/components/schemas/PipelineName"
        quotaLimit:
          $ref: "#/components/schemas/QuotaLimit"
        quotaConsumed:
          $ref: "#/components/schemas/QuotaConsumed"

    UpdatePipelineRequestBody:
      description: |
        json object containing the admin provided information to update a pipeline with
      type: object
      required: [ workspaceBillingProject, workspaceName, wdlMethodVersion ]
      properties:
        workspaceBillingProject:
          $ref: "#/components/schemas/PipelineWorkspaceBillingProject"
        workspaceName:
          $ref: "#/components/schemas/PipelineWorkspaceName"
        wdlMethodVersion:
          $ref: "#/components/schemas/PipelineWdlMethodVersion"

    UserId:
      description: |
        The identifier string for the user who submitted a job request.
      type: string
      format: string

  securitySchemes:
    oidc:
      type: oauth2
      x-tokenName: id_token
      flows:
        authorizationCode:
          authorizationUrl: "[[${authorityEndpoint}]]"
          scopes: { }
          tokenUrl: "[[${tokenEndpoint}]]"
    bearerAuth:
      type: http
      scheme: bearer

security:
  - oidc:
       - openid
  - bearerAuth: [ ]