openapi: 3.0.1
info:
title: Workflow Execution Service
version: 1.0.0
servers:
- url: /ga4gh/wes/v1
paths:
/service-info:
get:
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":
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceInfo'
description: ""
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: The request is malformed.
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: The request is unauthorized.
"403":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: The requester is not authorized to perform this action.
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: An unexpected error occurred.
summary: Get information about Workflow Execution Service.
tags:
- WorkflowExecutionService
x-swagger-router-controller: ga4gh.wes.server
/runs:
get:
description: This list should be provided in a stable ordering. (The actual
ordering is implementation dependent.) When paging through the list, the client
should not make assumptions about live updates, but should assume the contents
of the list reflect the workflow list at the moment that the first page is
requested. To monitor a specific workflow run, use GetRunStatus or GetRunLog.
operationId: ListRuns
parameters:
- description: OPTIONAL 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 if fewer than `page_size`
items are returned that all items have been returned. The availability
of additional pages is indicated by the value of `next_page_token` in the
response.
in: query
name: page_size
schema:
format: int64
type: integer
- description: OPTIONAL Token to use to indicate where to start getting results.
If unspecified, return the first page of results.
in: query
name: page_token
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/RunListResponse'
description: ""
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: The request is malformed.
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: The request is unauthorized.
"403":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: The requester is not authorized to perform this action.
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: An unexpected error occurred.
summary: List the workflow runs.
tags:
- WorkflowExecutionService
x-swagger-router-controller: ga4gh.wes.server
post:
description: |-
This endpoint creates a new workflow run and returns a `RunId` to monitor its progress.
The `workflow_attachment` array may be used to upload files that are required to execute the workflow, including the primary workflow, tools imported by the workflow, other files referenced by the workflow, or files which 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.
The `workflow_url` is either an absolute URL to a workflow file that is accessible by the WES endpoint, or a relative URL corresponding to one of the files attached using `workflow_attachment`.
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.
The `workflow_type` is the type of workflow language and must be "CWL" or "WDL" currently (or another alternative supported by this WES instance).
The `workflow_type_version` is the version of the workflow language submitted and must be one supported by this WES instance.
See the `RunRequest` documentation for details about other fields.
operationId: RunWorkflow
requestBody:
content:
multipart/form-data:
schema:
properties:
workflow_params:
format: application/json
type: string
workflow_type:
type: string
workflow_type_version:
type: string
tags:
format: application/json
type: string
workflow_engine_parameters:
format: application/json
type: string
workflow_url:
type: string
workflow_attachment:
items:
format: binary
type: string
type: array
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/RunId'
description: ""
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: The request is malformed.
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: The request is unauthorized.
"403":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: The requester is not authorized to perform this action.
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: An unexpected error occurred.
summary: Run a workflow.
tags:
- WorkflowExecutionService
x-swagger-router-controller: ga4gh.wes.server
/runs/{run_id}:
get:
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
parameters:
- in: path
name: run_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/RunLog'
description: ""
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: The request is unauthorized.
"403":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: The requester is not authorized to perform this action.
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: The requested workflow run not found.
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: An unexpected error occurred.
summary: Get detailed info about a workflow run.
tags:
- WorkflowExecutionService
x-swagger-router-controller: ga4gh.wes.server
/runs/{run_id}/cancel:
post:
operationId: CancelRun
parameters:
- in: path
name: run_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/RunId'
description: ""
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: The request is unauthorized.
"403":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: The requester is not authorized to perform this action.
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: The requested workflow run wasn't found.
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: An unexpected error occurred.
summary: Cancel a running workflow.
tags:
- WorkflowExecutionService
x-swagger-router-controller: ga4gh.wes.server
/runs/{run_id}/status:
get:
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
parameters:
- in: path
name: run_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/RunStatus'
description: ""
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: The request is unauthorized.
"403":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: The requester is not authorized to perform this action.
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: The requested workflow run wasn't found.
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: An unexpected error occurred.
summary: Get quick status info about a workflow run.
tags:
- WorkflowExecutionService
x-swagger-router-controller: ga4gh.wes.server
components:
schemas:
DefaultWorkflowEngineParameter:
description: A message that allows one to describe default parameters for a
workflow engine.
example:
name: name
default_value: default_value
type: type
properties:
name:
description: The name of the parameter
type: string
type:
description: Describes the type of the parameter, e.g. float.
type: string
default_value:
description: The stringified version of the default parameter. e.g. "2.45".
type: string
type: object
Log:
description: Log and other info
example:
start_time: start_time
stdout: stdout
name: name
end_time: end_time
exit_code: 0
cmd:
- cmd
- cmd
stderr: stderr
properties:
name:
description: The task or workflow name
type: string
cmd:
description: The command line that was executed
items:
type: string
type: array
start_time:
description: When the command started executing, in ISO 8601 format "%Y-%m-%dT%H:%M:%SZ"
type: string
end_time:
description: When the command stopped executing (completed, failed, or cancelled),
in ISO 8601 format "%Y-%m-%dT%H:%M:%SZ"
type: string
stdout:
description: A URL to retrieve standard output logs of the workflow run
or task. This URL may change between status requests, or may not be available
until the task or workflow has finished execution. Should be available
using the same credentials used to access the WES endpoint.
type: string
stderr:
description: A URL to retrieve standard error logs of the workflow run or
task. This URL may change between status requests, or may not be available
until the task or workflow has finished execution. Should be available
using the same credentials used to access the WES endpoint.
type: string
exit_code:
description: Exit code of the program
format: int32
type: integer
type: object
ServiceInfo:
description: A message containing useful information about the running service,
including supported versions and default settings.
example:
system_state_counts:
key: 0
supported_wes_versions:
- supported_wes_versions
- supported_wes_versions
supported_filesystem_protocols:
- supported_filesystem_protocols
- supported_filesystem_protocols
auth_instructions_url: auth_instructions_url
workflow_engine_versions:
key: workflow_engine_versions
contact_info_url: contact_info_url
workflow_type_versions:
key:
workflow_type_version:
- workflow_type_version
- workflow_type_version
default_workflow_engine_parameters:
- name: name
default_value: default_value
type: type
- name: name
default_value: default_value
type: type
tags:
key: tags
properties:
workflow_type_versions:
additionalProperties:
$ref: '#/components/schemas/WorkflowTypeVersion'
description: A map with keys as the workflow format type name (currently
only CWL and WDL are used although a service may support others) and value
is a workflow_type_version object which simply contains an array of one
or more version strings
type: object
supported_wes_versions:
description: The version(s) of the WES schema supported by this service
items:
type: string
type: array
supported_filesystem_protocols:
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.
items:
type: string
type: array
workflow_engine_versions:
additionalProperties:
type: string
description: The engine(s) used by this WES service, key is engine name
(e.g. Cromwell) and value is version
type: object
default_workflow_engine_parameters:
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.
items:
$ref: '#/components/schemas/DefaultWorkflowEngineParameter'
type: array
system_state_counts:
additionalProperties:
format: int64
type: integer
description: The system statistics, key is the statistic, value is the count
of runs in that state. See the State enum for the possible keys.
type: object
auth_instructions_url:
description: 'A web page URL with human-readable instructions on how to
get an authorization token for use with a specific WES endpoint. '
type: string
contact_info_url:
description: An email address URL (mailto:) or web page URL with contact
information for the operator of a specific WES endpoint. Users of the
endpoint should use this to report problems or security vulnerabilities.
type: string
tags:
additionalProperties:
type: string
description: A key-value map of arbitrary, extended metadata outside the
scope of the above but useful to report back
type: object
type: object
State:
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, so that a\
\ missing field does not accidentally imply that the state is QUEUED.\n\n\n\
\ - QUEUED: The task is queued.\n\n\n- 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.\n\n- RUNNING: The task is running.\
\ Input files are downloaded and the first Executor has been started.\n\n\
- PAUSED: The task is paused. An implementation may have the ability to pause\
\ a task, but this is not required.\n\n\n - COMPLETE: The task has completed\
\ running. Executors have exited without error\nand output files have been\
\ successfully uploaded.\n\n\n - EXECUTOR_ERROR: The task encountered an error\
\ in one of the Executor processes. Generally,\nthis means that an Executor\
\ exited with a non-zero exit code.\n\n\n - SYSTEM_ERROR: The task was stopped\
\ due to a system error, but not from an Executor,\nfor example an upload\
\ failed due to network issues, the worker's ran out of disk space, etc.\n\
\n\n - CANCELED: The task was canceled by the user.\n\n\n - CANCELING: The\
\ task was canceled by the user, and is in the process of stopping. "
enum:
- UNKNOWN
- QUEUED
- INITIALIZING
- RUNNING
- PAUSED
- COMPLETE
- EXECUTOR_ERROR
- SYSTEM_ERROR
- CANCELED
- CANCELING
type: string
RunListResponse:
description: The service will return a RunListResponse when receiving a successful
RunListRequest.
example:
next_page_token: next_page_token
runs:
- run_id: run_id
- run_id: run_id
properties:
runs:
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.
items:
$ref: '#/components/schemas/RunStatus'
type: array
next_page_token:
description: A token which may be supplied as `page_token` in workflow run
list request to get the next page of results. An empty string indicates
there are no more items to return.
type: string
type: object
RunLog:
example:
outputs: '{}'
request:
workflow_engine_parameters:
key: workflow_engine_parameters
workflow_url: workflow_url
workflow_params: '{}'
workflow_type: workflow_type
workflow_type_version: workflow_type_version
tags:
key: tags
run_id: run_id
run_log:
start_time: start_time
stdout: stdout
name: name
end_time: end_time
exit_code: 0
cmd:
- cmd
- cmd
stderr: stderr
task_logs:
- start_time: start_time
stdout: stdout
name: name
end_time: end_time
exit_code: 0
cmd:
- cmd
- cmd
stderr: stderr
- start_time: start_time
stdout: stdout
name: name
end_time: end_time
exit_code: 0
cmd:
- cmd
- cmd
stderr: stderr
properties:
run_id:
description: workflow run ID
type: string
request:
$ref: '#/components/schemas/RunRequest'
state:
$ref: '#/components/schemas/State'
run_log:
$ref: '#/components/schemas/Log'
task_logs:
description: The logs, and other key info like timing and exit code, for
each step in the workflow run.
items:
$ref: '#/components/schemas/Log'
type: array
outputs:
description: The outputs from the workflow run.
properties: {}
type: object
type: object
RunRequest:
description: |-
To execute a workflow, send a run request including all the details needed to begin downloading
and executing a given workflow.
example:
workflow_engine_parameters:
key: workflow_engine_parameters
workflow_url: workflow_url
workflow_params: '{}'
workflow_type: workflow_type
workflow_type_version: workflow_type_version
tags:
key: tags
properties:
workflow_params:
description: |-
REQUIRED
The workflow run parameterizations (JSON encoded), including input and output file locations
properties: {}
type: object
workflow_type:
description: |-
REQUIRED
The workflow descriptor type, must be "CWL" or "WDL" currently (or another alternative supported by this WES instance)
type: string
workflow_type_version:
description: |-
REQUIRED
The workflow descriptor type version, must be one supported by this WES instance
type: string
tags:
additionalProperties:
type: string
description: |-
OPTIONAL
A key-value map of arbitrary metadata outside the scope of `workflow_params` but useful to track with this run request
type: object
workflow_engine_parameters:
additionalProperties:
type: string
description: |-
OPTIONAL
Additional parameters can be sent to the workflow engine using this field. Default values for these parameters can be obtained using the ServiceInfo endpoint.
type: object
workflow_url:
description: |-
REQUIRED
The workflow CWL or WDL document. When `workflow_attachments` is used to attach files, the `workflow_url` may be a relative path to one of the attachments.
type: string
type: object
RunId:
example:
run_id: run_id
properties:
run_id:
description: workflow run ID
type: string
type: object
RunStatus:
description: Small description of a workflow run, returned by server during
listing
example:
run_id: run_id
properties:
run_id:
type: string
state:
$ref: '#/components/schemas/State'
required:
- run_id
type: object
WorkflowTypeVersion:
description: Available workflow types supported by a given instance of the service.
example:
workflow_type_version:
- workflow_type_version
- workflow_type_version
properties:
workflow_type_version:
description: an array of one or more acceptable types for the `workflow_type`
items:
type: string
type: array
type: object
ErrorResponse:
description: An object that can optionally include information about the error.
properties:
msg:
description: A detailed error message.
type: string
status_code:
description: The integer representing the HTTP status code (e.g. 200, 404).
type: integer
type: object