Clarify logs (expected to be URLs) and paging (use page_token). (#30)

* Clarify logs (expected to be URLs) and paging (use page_token).

Also clarify that timestamps should be ISO 8601.

* Update description for listing workflows and paging.

Be more precise based on feedback.

Revert text changes related to tags, will be brought up in a separate
PR.

openapi/workflow_execution_service.swagger.yaml

@@ -44,10 +44,13 @@ paths:
   /workflows:
     get:
       summary: |-
-        List the workflows, this endpoint will list the workflows in order of oldest to newest.
-        There is no guarantee of live updates as the user traverses the pages, the behavior should be
-        decided (and documented) by each implementation.
-        To monitor a given execution, use GetWorkflowStatus or GetWorkflowLog.
+        List submitted workflows.  This should be provided in a stable
+        ordering, however the ordering of this list 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 GetWorkflowStatus or GetWorkflowLog.
       x-swagger-router-controller: ga4gh.wes.server
       operationId: ListWorkflows
       responses:
@@ -75,15 +78,22 @@ paths:
         - name: page_size
           description: |-
             OPTIONAL
-            Number of workflows to return in a page.
+            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 is
+            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
           required: false
           type: integer
           format: int64
         - name: page_token
           description: |-
             OPTIONAL
-            Token to use to indicate where to start getting results. If unspecified, returns the first
+            Token to use to indicate where to start getting results. If unspecified, return the first
             page of results.
           in: query
           required: false
@@ -264,16 +274,26 @@ definitions:
         title: The command line that was run
       start_time:
         type: string
-        title: When the command was executed
+        title: When the command started executing, in ISO 8601 format "%Y-%m-%dT%H:%M:%SZ"
       end_time:
         type: string
-        title: When the command completed
+        title: When the command stopped executing (completed, failed, or cancelled), in ISO 8601 format "%Y-%m-%dT%H:%M:%SZ"
       stdout:
         type: string
-        title: Sample of stdout (not guaranteed to be entire log)
+        title: |-
+          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: Sample of stderr (not guaranteed to be entire log)
+        title: |-
+          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.
       exit_code:
         type: integer
         format: int32
@@ -396,8 +416,8 @@ definitions:
       next_page_token:
         type: string
         description: |-
-          A token, which when provided in a workflow_list_request, allows one to retrieve the next page
-          of results.
+          A token which may be supplied as "page_token" in workflow 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 workflow_list_response when receiving a successful workflow_list_request.
   WorkflowLog:
     type: object