Add simple run filtering on tag values

openapi/workflow_execution_service.openapi.yaml

@@ -1,23 +1,23 @@
 openapi: 3.0.0
 info:
   title: Workflow Execution Service
   contact: {}
   version: '1.1.0'
   x-logo:
     url: 'https://www.ga4gh.org/wp-content/themes/ga4gh-theme/gfx/GA-logo-horizontal-tag-RGB.svg'
   description: >
     *Run standard workflows on workflow execution platforms in a platform-agnostic way.*
 
     ## Executive Summary
 
     The Workflow Execution Service (WES) API provides a standard way for users to submit workflow requests to workflow execution systems, and to monitor their execution. This API lets users run a single workflow (currently [**CWL**](https://www.commonwl.org/) or [**WDL**](http://www.openwdl.org/) formatted workflows, other types may be supported in the future) 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, cmdline arguments)
     + can get information about running workflows (e.g. status, errors, output file locations)
     + can cancel a running workflow
 servers:
 - url: https://{defaultHost}/{basePath}/{apiVersion}
   variables:
@@ -183,6 +183,57 @@
       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:
+        - name: state
+          description: |-
+            OPTIONAL. Filter rubs by state. If unspecified,
+            no run state filtering is done.
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/RunStatus'
+        - name: tag_key
+          description: |-
+            OPTIONAL. Provide key tag to filter. The field tag_key is an array
+            of key values, and will be zipped with an optional tag_value array.
+            So the query:
+            ```
+              ?tag_key=foo1&tag_value=bar1&tag_key=foo2&tag_value=bar2
+            ```
+            Should be constructed into the structure { "foo1" : "bar1", "foo2" : "bar2"}
+
+            ```
+              ?tag_key=foo1
+            ```
+            Should be constructed into the structure {"foo1" : ""}
+
+            If the tag_value is empty, it will be treated as matching any possible value.
+            If a tag value is provided, both the tag's key and value must be exact
+            matches for a task to be returned.
+            Filter                            Tags                          Match?
+            ----------------------------------------------------------------------
+            {"foo": "bar"}                    {"foo": "bar"}                Yes
+            {"foo": "bar"}                    {"foo": "bat"}                No
+            {"foo": ""}                       {"foo": ""}                   Yes
+            {"foo": "bar", "baz": "bat"}      {"foo": "bar", "baz": "bat"}  Yes
+            {"foo": "bar"}                    {"foo": "bar", "baz": "bat"}  Yes
+            {"foo": "bar", "baz": "bat"}      {"foo": "bar"}                No
+            {"foo": ""}                       {"foo": "bar"}                Yes
+            {"foo": ""}                       {}                            No
+          in: query
+          required: false
+          schema:
+            type: array
+            items:
+              type: string
+        - name: tag_value
+          description: |-
+            OPTIONAL. The companion value field for tag_key
+          in: query
+          required: false
+          schema:
+            type: array
+            items:
+              type: string
         - name: page_size
           in: query
           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.