openapi: 3.0.0 info: title: >- GA4GH Workflow Execution Service API specification extended for the sapporo-service version: sapporo-wes-1.0.1-oas3 description: >- The Workflow Execution Service (WES) API provides a standard way for users to submit workflow requests to workflow execution systems and monitor their execution. This API lets users run a single workflow on multiple different platforms, clouds, and environments. Key features of the API: - can request that a workflow be run - can pass parameters to that workflow (e.g. input files, cmd-line arguments) - can get information about running workflows (e.g. status, errors, output file locations) - can cancel a running workflow license: url: https://github.com/sapporo-wes/sapporo-service/blob/main/LICENSE name: Apache-2.0 contact: url: https://github.com/sapporo-wes/sapporo-service/issues name: sapporo-wes - sapporo-service paths: /service-info: get: summary: Get information about Workflow Execution Service. description: >- May include information related (but not limited to) the workflow descriptor formats, versions supported, the WES API versions supported, and information about general service availability. operationId: GetServiceInfo responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/ServiceInfo" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal Server Error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /executable-workflows: get: summary: Get a list of executable workflows. description: >- Returns a list of all executable workflows. operationId: GetExecutableWorkflows responses: "200": description: OK content: application/json: schema: type: array items: $ref: "#/components/schemas/Workflow" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal Server Error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /parse-workflow: post: summary: Parse a workflow. description: >- The endpoint for parsing the workflow document. operationId: ParseWorkflow responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/ParseResult" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal Server Error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" requestBody: content: multipart/form-data: schema: $ref: "#/components/schemas/ParseRequest" /runs: get: summary: List the workflow runs. description: >- This list should be provided in a stable ordering. (The actual order is implementation-dependent.) When paging through the list, the client should not make assumptions about live updates but should assume the list's contents reflect the workflow list when the first page is requested. To monitor a specific workflow run, use `GetRunStatus` or `GetRunLog`. operationId: GetRunsList responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/RunListResponse" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal Server Error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" parameters: - name: page_size description: >- The preferred number of workflow runs to return in a page. If not provided, the implementation should use a default page size. The implementation must not return more items than `page_size`, but it may return fewer. Clients should not assume that all items have been returned if fewer than `page_size` items are returned. The value of `next_page_token` indicates the availability of additional pages in the response. in: query required: false schema: type: integer format: int64 - name: page_token description: >- Token to use to indicate where to start getting results. If unspecified, return the first page of results. in: query required: false schema: type: string post: summary: Run a workflow. description: >- This endpoint creates a new workflow run and returns a `RunId` to monitor its progress. operationId: RunWorkflow responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/RunId" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal Server Error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" requestBody: content: multipart/form-data: schema: $ref: "#/components/schemas/RunRequest" /runs/{run_id}: get: summary: Get detailed info about a workflow run. description: >- This endpoint provides detailed information about a given workflow run. The returned result has information about the outputs produced by this workflow (if available), a log object which allows the stderr and stdout to be retrieved, a log array so stderr/stdout for individual tasks can be retrieved, and the overall state of the workflow run (e.g. `RUNNING`, see the State section). operationId: GetRunLog responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/RunLog" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "404": description: The requested workflow run was not found. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal Server Error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" parameters: - name: run_id in: path required: true schema: type: string /runs/{run_id}/cancel: post: summary: Cancel a running workflow. operationId: CancelRun responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/RunId" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "404": description: The requested workflow run wasn't found. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal Server Error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" parameters: - name: run_id in: path required: true schema: type: string /runs/{run_id}/status: get: summary: Get quick status info about a workflow run. description: >- This provides an abbreviated (and likely fast depending on implementation) status of the running workflow, returning a simple result with the overall state of the workflow run (e.g. `RUNNING`, see the `State` section). operationId: GetRunStatus responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/RunStatus" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "404": description: The requested workflow run wasn't found. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal Server Error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" parameters: - name: run_id in: path required: true schema: type: string /runs/{run_id}/data/{path-to-file-or-dir}: get: summary: >- Download the files and directories under the run directory of the sapporo-service. description: >- This provides a remote url to download a file or directory under the `run_dir` of the sapporo-service. - In the case of `path/to/file`, this returns the download link for the file. - In the case of `path/to/dir`, this returns the list of files under the directory in JSON format. - In the case of `path/to/dir?download=true`, this returns the download link of the directory in zip format. The path is relative to the base directory of each run. See `README.md` in the sapporo-service for the structure of `run_dir`. For example, if you want to download the output `foo.txt`, specify something like `outputs/foo.txt`. `..` will be ignored. operationId: GetData responses: "200": description: OK content: application/json: schema: type: string format: binary "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "404": description: The requested workflow run wasn't found. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal Server Error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" parameters: - name: run_id in: path required: true schema: type: string - name: path-to-file-or-dir in: path required: true schema: type: string - name: download in: query schema: type: boolean components: schemas: WorkflowTypes: type: string nullable: true enum: - CWL - WDL - SMK - NFL description: The workflow type DefaultWorkflowEngineParameter: type: object additionalProperties: false required: - name - type - default_value properties: name: type: string description: The name of the parameter type: type: string description: Describes the type of the parameter, e.g., float. default_value: type: string description: The stringified version of the default parameter. e.g. 2.45. description: >- A message that allows one to describe default parameters for a workflow engine. Log: type: object additionalProperties: false required: - name - cmd - start_time - end_time - stdout - stderr - exit_code properties: name: type: string description: The task or workflow name cmd: type: array items: type: string description: The command line that was executed start_time: type: string format: datetime nullable: true description: >- When the command started executing, in ISO 8601 format `%Y-%m-%dT%H:%M:%SZ` end_time: type: string format: datetime nullable: true description: >- When the command stopped executing (completed, failed, or canceled), in ISO 8601 format `%Y-%m-%dT%H:%M:%SZ` stdout: type: string nullable: true description: >- A URL to retrieve standard output logs of the workflow run or task. This URL may change between status requests or be unavailable until the task or workflow has finished execution. It should be available using the same credentials used to access the WES endpoint. stderr: type: string nullable: true description: >- A URL to retrieve standard error logs of the workflow run or task. This URL may change between status requests or be unavailable until the task or workflow has finished execution. It should be available using the same credentials used to access the WES endpoint. exit_code: type: integer format: int32 nullable: true description: Exit code of the program description: >- The logs, and other key info like timing and exit code, for the overall run of this workflow. ServiceInfo: type: object additionalProperties: true required: - workflow_type_versions - supported_wes_versions - supported_filesystem_protocols - workflow_engine_versions - default_workflow_engine_parameters - system_state_counts - auth_instructions_url - contact_info_url - tags properties: workflow_type_versions: type: object properties: CWL: $ref: "#/components/schemas/WorkflowTypeVersion" WDL: $ref: "#/components/schemas/WorkflowTypeVersion" SMK: $ref: "#/components/schemas/WorkflowTypeVersion" NFL: $ref: "#/components/schemas/WorkflowTypeVersion" description: >- A map with keys as the workflow format type name (currently only CWL and WDL are used although service may support others) and value is a workflow_type_version object which contains an array of one or more version strings supported_wes_versions: type: array items: type: string description: The version(s) of the WES schema supported by this service supported_filesystem_protocols: type: array items: type: string description: >- The filesystem protocols supported by this service, currently these may include common protocols using the terms 'http', 'https', 'sftp', 's3', 'gs', 'file', or 'synapse', but others are possible and the terms beyond these core protocols are currently not fixed. This section reports those protocols (either common or not) supported by this WES service. workflow_engine_versions: type: object additionalProperties: type: string description: >- The engine(s) used by this WES service, the key is engine name (e.g., Cromwell), and value is version default_workflow_engine_parameters: type: object additionalProperties: type: array items: $ref: "#/components/schemas/DefaultWorkflowEngineParameter" description: >- Each workflow engine can present additional parameters that can be sent to the workflow engine. This message will list the default values and their types for each workflow engine. system_state_counts: type: object additionalProperties: type: integer format: int64 description: >- The system statistics, the key is the statistic, the value is the count of runs in that state. See the State enum for the possible keys. auth_instructions_url: type: string description: >- A web page URL with human-readable instructions on how to get an authorization token for use with a specific WES endpoint. contact_info_url: type: string description: >- An email address URL (mailto:) or web page URL with contact information for a specific WES endpoint operator. Users of the endpoint should use this to report problems or security vulnerabilities. tags: type: object additionalProperties: type: string description: >- A key-value map of arbitrary extended metadata outside the scope of the above but useful to report back description: >- A message containing helpful information about the running service, including supported versions and default settings. ParseRequest: type: object additionalProperties: false properties: workflow_content: type: string nullable: true description: The workflow content to be parsed workflow_location: type: string nullable: true description: The location of the workflow content types_of_parsing: type: array additionalProperties: true nullable: true items: type: string enum: - workflow_type - workflow_type_version - inputs - make_template description: The types of parsing to perform ParseResult: type: object required: - workflow_type - workflow_type_version - inputs properties: workflow_type: $ref: "#/components/schemas/WorkflowTypes" workflow_type_version: type: string nullable: true description: The workflow type version inputs: nullable: true oneOf: - type: array items: $ref: "#/components/schemas/WorkflowInput" - type: string description: The inputs to the workflow WorkflowInput: type: object additionalProperties: true properties: default: oneOf: - type: string - type: number - type: boolean nullable: true description: The default value for the input doc: type: string nullable: true description: The documentation for the input id: type: string description: The id of the input label: type: string nullable: true description: The label for the input type: type: string enum: - file - directory - any - string - number - boolean description: The type of the input array: type: boolean default: false description: Whether the input is an array required: type: boolean default: true description: Whether the input is required secondaryFiles: type: array nullable: true additionalProperties: false items: type: object additionalProperties: false required: - required - pattern properties: required: type: boolean description: Whether the secondary file is required pattern: type: string description: The pattern for the secondary file State: type: string enum: - UNKNOWN - QUEUED - INITIALIZING - RUNNING - PAUSED - COMPLETE - EXECUTOR_ERROR - SYSTEM_ERROR - CANCELED - CANCELING default: UNKNOWN description: >- - UNKNOWN: The state of the task is unknown. This provides a safe default for messages where this field is missing. For example, a missing field does not accidentally imply that the state is QUEUED. - QUEUED: The task is queued. - INITIALIZING: The task has been assigned to a worker and is currently preparing to run. For example, the worker may be turning on, downloading input files, etc. - RUNNING: The task is running. Input files are downloaded, and the first executor has been started. - PAUSED: The task is paused. An implementation may have the ability to pause a task, but this is not required. - COMPLETE: The task has been completed running. Executors have exited without error, and output files have been successfully uploaded. - EXECUTOR_ERROR: The task encountered an error in one of the Executor processes. Generally, this means that an Executor exited with a non-zero exit code. - SYSTEM_ERROR: The task was stopped due to a system error, but not from an Executor; for example, an upload failed due to network issues, the workers ran out of disk space, etc. - CANCELED: The task was canceled by the user. - CANCELING: The task was canceled by the user and is in the process of stopping. RunListResponse: type: object additionalProperties: false required: - runs properties: runs: type: array additionalProperties: false items: $ref: "#/components/schemas/RunStatus" description: >- A list of workflow runs that the service has executed or is executing. The list is filtered to only include runs that the caller has permission to see. next_page_token: type: string description: >- A token may be supplied as `page_token` in the workflow run list request to get the next page of results. An empty string indicates there are no more items to return. description: >- The service will return a RunListResponse when receiving a successful RunListRequest. RunLog: type: object additionalProperties: false required: - run_id - request - state - run_log - task_logs - outputs properties: run_id: type: string description: workflow run ID request: $ref: "#/components/schemas/RunRequest" state: $ref: "#/components/schemas/State" run_log: $ref: "#/components/schemas/Log" task_logs: type: array items: $ref: "#/components/schemas/Log" nullable: true description: >- The logs, and other key info like timing and exit code, for each step in the workflow run. outputs: type: array additionalProperties: false items: $ref: "#/components/schemas/AttachedFile" description: The outputs from the workflow run. RunRequest: type: object additionalProperties: false required: - workflow_engine_name properties: workflow_params: type: string format: application/json nullable: true description: >- The `workflow_params` JSON object specifies input parameters, such as input files. The exact format of the JSON object depends on the conventions of the workflow language being used. Input files should either be absolute URLs or relative URLs corresponding to files uploaded using `workflow_attachment`. The WES endpoint must understand and be able to access URLs supplied in the input. This is implementation-specific. workflow_type: type: string nullable: true description: >- The `workflow_type` is the type of workflow language. workflow_type_version: type: string nullable: true description: >- The `workflow_type_version` is the version of the workflow language submitted and must be one supported by this WES instance. tags: type: string nullable: true format: application/json description: >- A key-value map of arbitrary metadata outside the scope of `workflow_params` but useful to track with this run request workflow_engine_name: type: string description: >- Specify the name of the workflow engine to run a workflow. workflow_engine_parameters: type: string format: application/json nullable: true description: >- Additional parameters can be sent to the workflow engine using this field. Default values for these parameters can be obtained using the `GetServiceInfo` endpoint. workflow_url: type: string nullable: true description: >- The workflow CWL or WDL document. When `workflow_attachment` is used to attach files, the `workflow_url` may be a relative path to one of the attachments. workflow_name: type: string nullable: true description: >- The `workflow_name` is used to execute the workflow registered in the sapporo-service. Please request to `GetServiceInfo` to check registered workflows. If `workflow_name` is specified, `workflow_url`, `workflow_type` and `workflow_type_version` will be ignored. workflow_attachment: anyOf: - type: array items: type: string format: binary - type: string format: application/json nullable: true description: >- The `workflow_attachment` array may be used to upload files required to execute the workflow, including the primary workflow, tools imported by the workflow, other files referenced by the workflow, or files that are part of the input. The implementation should stage these files to a temporary directory and execute the workflow from there. These parts must have a Content-Disposition header with a "filename" provided for each part. Filenames may include subdirectories but must not include references to parent directories with '..' -- implementations should guard against maliciously constructed filenames. As a workflow attachment, it returns a list of files attached to the run request. The file_url is generated by using the file distribution feature of the sapporo-service server. A JSON encoded string from `List[AttachedFile]`. The sapporo-service will download the file to the execution directory. description: >- To execute a workflow, send a run request including all the details needed to begin downloading and managing a given workflow. RunId: type: object additionalProperties: false required: - run_id properties: run_id: type: string description: workflow run ID RunStatus: type: object required: - run_id - state properties: run_id: type: string state: $ref: "#/components/schemas/State" description: Small description of a workflow run, returned by server during listing WorkflowTypeVersion: type: object additionalProperties: false required: - workflow_type_version properties: workflow_type_version: type: array items: type: string description: an array of one or more acceptable types for the `workflow_type` description: Available workflow types supported by a given instance of the service. ErrorResponse: description: >- An object that can optionally include information about the error. type: object additionalProperties: false required: - msg - status_code properties: msg: type: string description: A detailed error message. status_code: type: integer description: The integer representing the HTTP status code (e.g. 200, 404). Workflow: type: object additionalProperties: false required: - workflow_name - workflow_type - workflow_type_version - workflow_url - workflow_attachment properties: workflow_name: type: string description: The workflow name workflow_url: type: string description: The workflow document workflow_type: type: string description: >- The workflow descriptor type must be "CWL" or "WDL" currently (or another alternative supported by this WES instance) workflow_type_version: type: string description: >- A map with keys as the workflow format type name (currently only CWL and WDL are used although service may support others) and value is a workflow_type_version object which contains an array of one or more version strings workflow_attachment: type: array additionalProperties: false items: $ref: "#/components/schemas/AttachedFile" description: >- The workflow_attachment array may be used to download files required to execute the workflow, including the primary workflow, tools imported by the workflow, other files referenced by the workflow, or files that are part of the input. The implementation should stage these files to a temporary directory and execute the workflow from there. description: >- The information about the workflow is provided by `GetServiceInfo` in the mode of executing only the workflow registered by the administrator. AttachedFile: type: object additionalProperties: false required: - file_name - file_url properties: file_name: type: string description: File name. It can be also specified like `dir_name/file_name`. file_url: type: string description: Remote file URL.