xenon-workflow-execution-api.yaml

openapi: 3.0.1
info:
  title: Xenon CWL workflow execution service API
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
servers:
- url: /
paths:
  /jobs:
    get:
      summary: list of jobs
      description: get a list of all jobs, running, cancelled, or otherwise.
      operationId: getJobs
      responses:
        200:
          description: list of jobs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/job'
              example:
              - id: afcd1554-9604-11e6-bd3f-080027e8b32a
                input:
                  file1:
                    class: File
                    location: whale.txt
                log: http://localhost:5000/jobs/afcd1554-9604-11e6-bd3f-080027e8b32a/stderr
                name: myjob1
                output:
                  output:
                    checksum: sha1$6f9bd042bff934443cc65f7ef769613222f7b136
                    basename: output
                    location: file:///tmp/afcd1554-9604-11e6-bd3f-080027e8b32a/output
                    path: /tmp/afcd1554-9604-11e6-bd3f-080027e8b32a/output
                    class: File
                    size: 9
                state: Success
                workflow: wc-tool.cwl
    post:
      summary: submit a new job
      description: Submit a new job from a workflow definition.
      operationId: postJob
      requestBody:
        description: Input binding for workflow.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/job-description'
        required: true
      responses:
        201:
          description: OK
          headers:
            Location:
              description: uri of the created job
              schema:
                type: string
                format: uri
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/job'
              example:
                id: afcd1554-9604-11e6-bd3f-080027e8b32a
                input:
                  file1:
                    class: File
                    location: whale.txt
                log: http://localhost:5000/jobs/afcd1554-9604-11e6-bd3f-080027e8b32a/log
                name: myjob1
                output: {}
                state: Running
                workflow: wc-tool.cwl
      x-codegen-request-body-name: body
  /jobs/{jobId}:
    get:
      summary: Get a job
      operationId: getJobById
      parameters:
      - name: jobId
        in: path
        description: Job ID
        required: true
        schema:
          type: string
      responses:
        200:
          description: Status of job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/job'
              example:
                id: afcd1554-9604-11e6-bd3f-080027e8b32a
                input:
                  file1:
                    class: File
                    location: whale.txt
                log: http://localhost:5000/jobs/afcd1554-9604-11e6-bd3f-080027e8b32a/log
                name: myjob1
                output:
                  output:
                    checksum: sha1$6f9bd042bff934443cc65f7ef769613222f7b136
                    basename: output
                    location: file:///tmp/afcd1554-9604-11e6-bd3f-080027e8b32a/output
                    path: /tmp/afcd1554-9604-11e6-bd3f-080027e8b32a/output
                    class: File
                    size: 9
                state: Success
                workflow: wc-tool.cwl
        404:
          description: Job not found
          content: {}
    delete:
      summary: Delete a job
      description: Delete a job, if job is in waiting or running state then job will
        be cancelled first.
      operationId: deleteJobById
      parameters:
      - name: jobId
        in: path
        description: Job ID
        required: true
        schema:
          type: string
      responses:
        204:
          description: Job deleted
          content: {}
        404:
          description: Job not found
          content: {}
  /jobs/{jobId}/cancel:
    post:
      summary: Cancel a job
      operationId: cancelJobById
      parameters:
      - name: jobId
        in: path
        description: Job ID
        required: true
        schema:
          type: string
      responses:
        200:
          description: Job has been cancelled if job was still running or waiting
          headers:
            Location:
              description: uri of the cancelled job
              schema:
                type: string
                format: uri
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/job'
            application/json:
              example:
                id: afcd1554-9604-11e6-bd3f-080027e8b32a
                input:
                  file1:
                    class: File
                    location: whale.txt
                log: http://localhost:5000/jobs/afcd1554-9604-11e6-bd3f-080027e8b32a/log
                name: myjob1
                output:
                  output:
                    checksum: sha1$6f9bd042bff934443cc65f7ef769613222f7b136
                    basename: output
                    location: file:///tmp/afcd1554-9604-11e6-bd3f-080027e8b32a/output
                    path: /tmp/afcd1554-9604-11e6-bd3f-080027e8b32a/output
                    class: File
                    size: 9
                state: Cancelled
                workflow: wc-tool.cwl
        404:
          description: Job not found
          content: {}
  /jobs/{jobId}/log:
    get:
      summary: Log of a job
      operationId: getJobLogById
      parameters:
      - name: jobId
        in: path
        description: Job ID
        required: true
        schema:
          type: string
      responses:
        200:
          description: Job log
          content:
            text/plain:
              schema:
                type: string
        302:
          description: Job log redirect
          headers:
            Location:
              description: uri of the log of the job
              schema:
                type: string
                format: uri
          content:
            text/plain:
              example: |
                [job wc-tool.cwl] /tmp/afcd1554-9604-11e6-bd3f-080027e8b32a$ wc < /tmp/afcd1554-9604-11e6-bd3f-080027e8b32a/stge84d1078-e33f-41c3-8714-aafe955d1b53/whale.txt > /tmp/afcd1554-9604-11e6-bd3f-080027e8b32a/output
                Final process status is success
        404:
          description: Job not found
          content: {}
  /status:
    get:
      summary: Get the server status
      operationId: getServerStatus
      responses:
        200:
          description: The server status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/status'
              example:
                waiting: 3
                running: 1
                successful: 10
                errored: 4
  /workflows:
    get:
      summary: A list of available workflows
      operationId: getWorkflows
      responses:
        200:
          description: The list of available workflows
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/workflow'
              example:
                - filename: echo.cwl
                  path: cwl/echo.cwl
                - filename: my_workflow.cwl
                  path: science/my_workflow.cwl
components:
  schemas:
    workflow-binding:
      type: object
    job-description:
      required:
      - workflow
      type: object
      properties:
        name:
          type: string
          description: user supplied (non unique) name for this job
          example: myjob1
        workflow:
          type: string
          description: location of the workflow
          format: uri
          example: wc-tool.cwl
        input:
          $ref: '#/components/schemas/workflow-binding'
      example:
        name: myjob1
        workflow: wc-tool.cwl
        input:
          file1:
            class: File
            location: whale.txt
    job:
      required:
      - id
      - input
      - log
      - name
      - output
      - state
      - workflow
      type: object
      properties:
        id:
          type: string
          format: uri
          example: afcd1554-9604-11e6-bd3f-080027e8b32a
        name:
          type: string
          description: user supplied (non unique) name for this job
          example: myjob1
        workflow:
          type: string
          description: location of the workflow
          format: uri
          example: wc-tool.cwl
        input:
          $ref: '#/components/schemas/workflow-binding'
        state:
          type: string
          example: Running
          enum:
          - Waiting
          - Running
          - Success
          - Cancelled
          - SystemError
          - TemporaryFailure
          - PermanentFailure
        output:
          $ref: '#/components/schemas/workflow-binding'
        log:
          type: string
          format: uri
          example: http://localhost:5000/jobs/afcd1554-9604-11e6-bd3f-080027e8b32a/log
        additionalInfo:
          type: object
          properties: {}
    file:
      required:
      - id
      - type
      type: object
      properties:
        id:
          type: string
          example: input_file
        type:
          type: string
          example: File
    workflow:
      required:
      - filename
      - path
      type: object
      properties:
        filename:
          type: string
          example: echo.cwl
        path:
          type: string
          example: cwl/echo.cwl
    status:
      required:
      - waiting
      - running
      - successful
      - errored
      type: object
      properties:
        waiting:
          type: integer
          example: 2
        running:
          type: integer
          example: 2
        successful:
          type: integer
          example: 2
        errored:
          type: integer
          example: 2
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: 'api-key'
security:
  - ApiKeyAuth: []