Add query watches api to retrieve multiple watches. (#65813)

Backport #64582 to 7.x branch.

This api supports pagination (from / size) and
querying and sorting by watch _id and watcher metadata.

This avoids using .watch index directly.
On a per watch basis the same information that the get watch api returns is returned,
except version.

Relates #62501

Author: martijnvg

x-pack/docs/en/rest-api/watcher.asciidoc

@@ -4,6 +4,7 @@
 
 * <<watcher-api-put-watch>>
 * <<watcher-api-get-watch>>
+* <<watcher-api-query-watches>>
 * <<watcher-api-delete-watch>>
 * <<watcher-api-execute-watch>>
 * <<watcher-api-ack-watch>>
@@ -26,9 +27,11 @@ include::watcher/execute-watch.asciidoc[]
 //GET
 include::watcher/get-watch.asciidoc[]
 include::watcher/stats.asciidoc[]
+//QUERY
+include::watcher/query-watches.asciidoc[]
 //PUT
 include::watcher/put-watch.asciidoc[]
 //START
 include::watcher/start.asciidoc[]
 //STOP
-include::watcher/stop.asciidoc[]
+include::watcher/stop.asciidoc[]

x-pack/docs/en/rest-api/watcher/query-watches.asciidoc

@@ -0,0 +1,131 @@
+[role="xpack"]
+[[watcher-api-query-watches]]
+=== Query watches API
+++++
+<titleabbrev>Query watches</titleabbrev>
+++++
+
+Retrieves all registered watches.
+
+[[watcher-api-query-watches-request]]
+==== {api-request-title}
+
+`GET /_watcher/_query/watches`
+
+[[watcher-api-query-watches-prereqs]]
+==== {api-prereq-title}
+
+* You must have `manage_watcher` or `monitor_watcher` cluster privileges to use
+this API. For more information, see <<security-privileges>>.
+
+//[[watcher-api-query-watches-desc]]
+//==== {api-description-title}
+
+Retrieves all watches in a paginated manner and
+optionally filtering watches by a query.
+
+//[[watcher-api-query-watches-request-body]]
+//==== {api-request-body-title}
+
+This API supports the following fields:
+
+[cols=",^,^,", options="header"]
+|======
+| Name              | Required | Default  | Description
+
+| `from`            | no       | 0        | The offset from the first result to fetch. Needs to be non-negative.
+
+| `size`            | no       | 10       | The number of hits to return. Needs to be non-negative.
+
+| `query`           | no       | null     | Optional, <<query-dsl,query>> filter  watches to be returned.
+
+| `sort`            | no       | null     | Optional <<search-request-sort,sort definition>>.
+
+| `search_after`    | no       | null     | Optional <<search-request-search-after,search After>> to do pagination
+                                            using last hit's sort values.
+|======
+
+Note that only the `_id` and `metadata.*` fields are queryable or sortable.
+
+//[[watcher-api-query-watches-response-body]]
+//==== {api-response-body-title}
+
+This api returns the following top level fields:
+
+`count`::
+    The total number of watches found.
+
+`watches`::
+    A list of watches based on the `from`, `size` or `search_after` request body parameters.
+
+[[watcher-api-query-watches-example]]
+==== {api-examples-title}
+
+The following example list all stored watches:
+
+[source,console]
+--------------------------------------------------
+GET /_watcher/_query/watches
+--------------------------------------------------
+// TEST[setup:my_active_watch]
+
+Response:
+
+[source,console-result]
+--------------------------------------------------
+{
+    "count": 1,
+    "watches": [
+        {
+            "_id": "my_watch",
+            "watch": {
+                "trigger": {
+                    "schedule": {
+                        "hourly": {
+                            "minute": [
+                                0,
+                                5
+                            ]
+                        }
+                    }
+                },
+                "input": {
+                    "simple": {
+                        "payload": {
+                            "send": "yes"
+                        }
+                    }
+                },
+                "condition": {
+                    "always": {}
+                },
+                "actions": {
+                    "test_index": {
+                        "index": {
+                            "index": "test"
+                        }
+                    }
+                }
+            },
+            "status": {
+                "state": {
+                    "active": true,
+                    "timestamp": "2015-05-26T18:21:08.630Z"
+                },
+                "actions": {
+                    "test_index": {
+                        "ack": {
+                            "timestamp": "2015-05-26T18:21:08.630Z",
+                            "state": "awaits_successful_execution"
+                        }
+                    }
+                },
+                "version": -1
+            },
+            "_seq_no": 0,
+            "_primary_term": 1
+        }
+    ]
+}
+--------------------------------------------------
+// TESTRESPONSE[s/"timestamp": "2015-05-26T18:21:08.630Z"/"timestamp": "$body.watches.0.status.state.timestamp"/]