openapi: 3.0.1 info: title: Workflow Execution Service version: 1.0.0 servers: - url: /ga4gh/wes/v1 paths: /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: list_runs 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 x-openapi-router-controller: rest_api.controllers.workflow_execution_service_controller 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: run_workflow requestBody: content: multipart/form-data: schema: type: object 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 x-openapi-router-controller: rest_api.controllers.workflow_execution_service_controller /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: get_run_log 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 x-openapi-router-controller: rest_api.controllers.workflow_execution_service_controller /runs/{run_id}/cancel: post: operationId: cancel_run 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 x-openapi-router-controller: rest_api.controllers.workflow_execution_service_controller /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: get_run_status 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 x-openapi-router-controller: rest_api.controllers.workflow_execution_service_controller /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: get_service_info 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 x-openapi-router-controller: rest_api.controllers.workflow_execution_service_controller 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