Skip to content

Commit

Permalink
Merge branch 'develop' into dglazer-doccleanup-oct02
Browse files Browse the repository at this point in the history
  • Loading branch information
@briandoconnor
briandoconnor authored Oct 2, 2018
2 parents da4857a + eca1f5d commit 5494f19
Showing 1 changed file with 46 additions and 53 deletions.
99 changes: 46 additions & 53 deletions openapi/workflow_execution_service.swagger.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ paths:
/runs:
get:
summary: List the workflow runs.
description: |-
description: >-
This list should be provided in a stable ordering.
(The actual ordering is implementation dependent.)
When paging through the list, the client should
Expand Down Expand Up @@ -76,7 +76,7 @@ paths:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: page_size
description: |-
description: >-
OPTIONAL
The preferred number of workflow runs to return in a page.
If not provided, the implementation should use a default page size.
Expand All @@ -91,7 +91,7 @@ paths:
type: integer
format: int64
- name: page_token
description: |-
description: >-
OPTIONAL
Token to use to indicate where to start getting results. If unspecified, return the first
page of results.
Expand All @@ -102,7 +102,7 @@ paths:
- WorkflowExecutionService
post:
summary: Run a workflow.
description: |-
description: >-
This endpoint creates a new workflow run and
returns a `RunId` to monitor its progress.
Expand All @@ -118,11 +118,13 @@ paths:
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
Expand All @@ -131,11 +133,13 @@ paths:
`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.

Expand Down Expand Up @@ -205,7 +209,7 @@ paths:
/runs/{run_id}:
get:
summary: Get detailed info about a workflow run.
description: |-
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,
Expand Down Expand Up @@ -277,7 +281,7 @@ paths:
/runs/{run_id}/status:
get:
summary: Get quick status info about a workflow run.
description: |-
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).
Expand Down Expand Up @@ -317,44 +321,44 @@ definitions:
properties:
name:
type: string
description: 'The name of the parameter'
description: The name of the parameter
type:
type: string
description: 'Describes the type of the parameter, e.g. float.'
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: |-
description: >-
A message that allows one to describe default parameters for a workflow
engine.
Log:
type: object
properties:
name:
type: string
title: The task or workflow name
description: The task or workflow name
cmd:
type: array
items:
type: string
title: The command line that was executed
description: The command line that was executed
start_time:
type: string
title: When the command started executing, in ISO 8601 format "%Y-%m-%dT%H:%M:%SZ"
description: When the command started executing, in ISO 8601 format "%Y-%m-%dT%H:%M:%SZ"
end_time:
type: string
title: When the command stopped executing (completed, failed, or cancelled), in ISO 8601 format "%Y-%m-%dT%H:%M:%SZ"
description: When the command stopped executing (completed, failed, or cancelled), in ISO 8601 format "%Y-%m-%dT%H:%M:%SZ"
stdout:
type: string
title: |-
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.
stderr:
type: string
title: |-
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
Expand All @@ -363,34 +367,29 @@ definitions:
exit_code:
type: integer
format: int32
title: Exit code of the program
title: Log and other info
description: Exit code of the program
description: Log and other info
ServiceInfo:
type: object
properties:
workflow_type_versions:
type: object
additionalProperties:
$ref: '#/definitions/WorkflowTypeVersion'
title: |-
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
description: |-
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
supported_wes_versions:
type: array
items:
type: string
title: The version(s) of the WES schema supported by this service
description: The version(s) of the WES schema supported by this service
supported_filesystem_protocols:
type: array
items:
type: string
description: |-
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.
Expand All @@ -399,13 +398,13 @@ definitions:
type: object
additionalProperties:
type: string
title: 'The engine(s) used by this WES service, key is engine name e.g. Cromwell and value is version'
description: The engine(s) used by this WES service, key is engine name (e.g. Cromwell) and value is version
description: >-
The engine(s) used by this WES service, key is engine name (e.g. Cromwell) and value is version
default_workflow_engine_parameters:
type: array
items:
$ref: '#/definitions/DefaultWorkflowEngineParameter'
description: |-
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.
Expand All @@ -414,32 +413,29 @@ definitions:
additionalProperties:
type: integer
format: int64
description: |-
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.
auth_instructions_url:
type: string
description: |-
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 (mailto) or web page URL with contact information
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.
tags:
type: object
additionalProperties:
type: string
title: |-
A key-value map of arbitrary, extended metadata outside the scope of the above but useful
to report back
description: |-
description: >-
A key-value map of arbitrary, extended metadata outside the scope of the above but useful
to report back
description: |-
description: >-
A message containing useful information about the running service, including supported versions and
default settings.
State:
Expand Down Expand Up @@ -477,20 +473,19 @@ definitions:
for example an upload failed due to network issues, the worker's ran out
of disk space, etc.
- CANCELED: The task was canceled by the user.
title: Enumeration of states for a given run request
RunListResponse:
type: object
properties:
runs:
type: array
items:
$ref: '#/definitions/RunStatus'
description: |-
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: |-
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.
description: The service will return a RunListResponse when receiving a successful RunListRequest.
Expand All @@ -499,28 +494,23 @@ definitions:
properties:
run_id:
type: string
title: workflow run ID
description: workflow run ID
request:
$ref: '#/definitions/RunRequest'
description: The original request message used to initiate this execution.
state:
$ref: '#/definitions/State'
title: state
description: The state of the run e.g. RUNNING (see State)
run_log:
$ref: '#/definitions/Log'
title: 'the logs, and other key info like timing and exit code, for the overall run of this workflow'
description: The logs, and other key info like timing and exit code, for the overall run of this workflow.
task_logs:
type: array
items:
$ref: '#/definitions/Log'
title: 'the logs, and other key info like timing and exit code, for each step in the workflow run'
description: The logs, and other key info like timing and exit code, for each step in the workflow run.
outputs:
type: object
title: a JSON dictionary of the outputs
description: The outputs from the workflow run.
RunRequest:
type: object
Expand All @@ -532,12 +522,12 @@ definitions:
The workflow run parameterizations (JSON encoded), including input and output file locations
workflow_type:
type: string
title: |-
description: |-
REQUIRED
The workflow descriptor type, must be "CWL" or "WDL" currently (or another alternative supported by this WES instance)
workflow_type_version:
type: string
title: |-
description: |-
REQUIRED
The workflow descriptor type version, must be one supported by this WES instance
tags:
Expand All @@ -551,14 +541,16 @@ definitions:
type: object
additionalProperties:
type: string
description: |-
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.
workflow_url:
type: string
description: |-
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.
Expand All @@ -570,7 +562,7 @@ definitions:
properties:
run_id:
type: string
title: workflow run ID
description: workflow run ID
RunStatus:
type: object
required:
Expand All @@ -580,7 +572,7 @@ definitions:
type: string
state:
$ref: '#/definitions/State'
description: 'Small description of a workflow run, returned by server during listing'
description: Small description of a workflow run, returned by server during listing
WorkflowTypeVersion:
type: object
properties:
Expand All @@ -590,9 +582,10 @@ definitions:
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: |-
description: >-
An object that can optionally include information about the error.
type: object
properties:
Expand Down

0 comments on commit 5494f19

Please sign in to comment.