Format Watcher APIs (elastic/x-pack-elasticsearch#2382)

* [DOCS] Format Watcher APIs

* [DOCS] Removed master_timeout from Watcher APIs

* [DOCS] Added authority info to watcher APIs

Original commit: elastic/x-pack-elasticsearch@1e6de3b036

docs/en/rest-api/watcher/ack-watch.asciidoc

@@ -2,9 +2,37 @@
 [[watcher-api-ack-watch]]
 === Ack Watch API
 
-{xpack-ref}/actions.html#actions-ack-throttle[Acknowledging a watch] enables you to manually throttle
+{xpack-ref}/actions.html#actions-ack-throttle[Acknowledging a watch] enables you
-execution of the watch's actions. An action's _acknowledgement state_ is stored
+to manually throttle execution of the watch's actions. An action's
-in the `status.actions.<id>.ack.state` structure.
+_acknowledgement state_ is stored in the `status.actions.<id>.ack.state`
+structure.
+
+[float]
+==== Request
+
+`PUT _xpack/watcher/watch/<watch_id>/_ack` +
+
+`PUT _xpack/watcher/watch/<watch_id>/_ack/<action_id>`
+
+[float]
+==== Path Parameters
+
+`action_id`::
+  (list) A comma-separated list of the action IDs to acknowledge. If you omit
+  this parameter, all of the actions of the watch are acknowledged.
+
+`watch_id` (required)::
+  (string) Identifier for the watch.
+
+[float]
+==== Authorization
+
+You must have `manage_watcher` cluster privileges to use this API. For more
+information, see {xpack-ref}/security-privileges.html[Security Privileges].
+
+
+[float]
+==== Examples
 
 To demonstrate let's create a new watch:
 

docs/en/rest-api/watcher/activate-watch.asciidoc

@@ -6,6 +6,26 @@ A watch can be either
 {xpack-ref}/how-watcher-works.html#watch-active-state[active or inactive]. This
 API enables you to activate a currently inactive watch.
 
+[float]
+==== Request
+
+`PUT _xpack/watcher/watch/<watch_id>/_activate`
+
+[float]
+==== Path Parameters
+
+`watch_id` (required)::
+  (string) Identifier for the watch.
+
+[float]
+==== Authorization
+
+You must have `manage_watcher` cluster privileges to use this API. For more
+information, see {xpack-ref}/security-privileges.html[Security Privileges].
+
+[float]
+==== Examples
+
 The status of an inactive watch is returned with the watch definition when you
 call the <<watcher-api-get-watch, Get Watch API>>:
 

docs/en/rest-api/watcher/deactivate-watch.asciidoc

@@ -6,6 +6,25 @@ A watch can be either
 {xpack-ref}/how-watcher-works.html#watch-active-state[active or inactive]. This
 API enables you to deactivate a currently active watch.
 
+[float]
+==== Request
+
+`PUT _xpack/watcher/watch/<watch_id>/_deactivate`
+
+[float]
+==== Path Parameters
+
+`watch_id` (required)::
+  (string) Identifier for the watch.
+
+[float]
+==== Authorization
+You must have `manage_watcher` cluster privileges to use this API. For more
+information, see {xpack-ref}/security-privileges.html[Security Privileges].
+
+[float]
+==== Examples
+
 The status of an active watch is returned with the watch definition when you
 call the <<watcher-api-get-watch, Get Watch API>>:
 

docs/en/rest-api/watcher/delete-watch.asciidoc

@@ -2,18 +2,42 @@
 [[watcher-api-delete-watch]]
 === Delete Watch API
 
-The DELETE watch API removes a watch (identified by its `id`) from {watcher}.
+The DELETE watch API removes a watch from {watcher}.
-Once removed, the document representing the watch in the `.watches` index is
+
-gone and it will never be executed again.
+[float]
+==== Request
+
+`DELETE _xpack/watcher/watch/<watch_id>`
+
+[float]
+==== Description
+
+When the watch is removed, the document representing the watch in the `.watches`
+index is gone and it will never be run again.
 
 Please note that deleting a watch **does not** delete any watch execution records
 related to this watch from the watch history.
 
 IMPORTANT:  Deleting a watch must be done via this API only. Do not delete the
-            watch directly from the `.watches` index using Elasticsearch's
+            watch directly from the `.watches` index using the Elasticsearch
             DELETE Document API. When {security} is enabled, make sure no `write`
             privileges are granted to anyone over the `.watches` index.
 
+[float]
+==== Path Parameters
+
+`watch_id` (required)::
+  (string) Identifier for the watch.
+
+[float]
+==== Authorization
+
+You must have `manage_watcher` cluster privileges to use this API. For more
+information, see {xpack-ref}/security-privileges.html[Security Privileges].
+
+[float]
+==== Examples
+
 The following example deletes a watch with the `my-watch` id:
 
 [source,js]
@@ -34,4 +58,3 @@ Response:
 }
 --------------------------------------------------
 // TESTRESPONSE
-

docs/en/rest-api/watcher/execute-watch.asciidoc

@@ -6,20 +6,45 @@ The execute watch API forces the execution of a stored watch. It can be used to
 force execution of the watch outside of its triggering logic, or to simulate the
 watch execution for debugging purposes.
 
-The following example executes the `my_watch` watch:
+[float]
+==== Request
 
-[source,js]
+`POST _xpack/watcher/watch/<watch_id>/_execute` +
---------------------------------------------------
-POST _xpack/watcher/watch/my_watch/_execute
---------------------------------------------------
-// CONSOLE
-// TEST[setup:my_active_watch]
 
-For testing and debugging purposes, you also have fine-grained control on how the
+`POST _xpack/watcher/watch/_execute`
-watch is executed--execute the watch without executing all of its actions or
+
-alternatively by simulating them. You can also force execution by ignoring the
+[float]
-watch condition and control whether a watch record would be written to the watch
+==== Description
-history after execution.
+
+For testing and debugging purposes, you also have fine-grained control on how
+the watch runs. You can execute the watch without executing all of its actions
+or alternatively by simulating them. You can also force execution by ignoring
+the watch condition and control whether a watch record would be written to the
+watch history after execution.
+
+[float]
+[[watcher-api-execute-inline-watch]]
+===== Inline Watch Execution
+
+You can use the Execute API to execute watches that are not yet registered by
+specifying the watch definition inline. This serves as great tool for testing
+and debugging your watches prior to adding them to {watcher}.
+
+[float]
+==== Path Parameters
+
+`watch_id`::
+  (string) Identifier for the watch.
+
+[float]
+==== Query Parameters
+
+`debug`::
+  (boolean) Defines whether the watch runs in debug mode. The default value is
+  `false`.
+
+[float]
+==== Request Body
 
 This API supports the following fields:
 
@@ -53,6 +78,58 @@ This API supports the following fields:
                                               not persisted to the index and record_execution cannot be set.
 |======
 
+[float]
+[[watcher-api-execute-watch-action-mode]]
+===== Action Execution Modes
+
+Action modes define how actions are handled during the watch execution. There
+are five possible modes an action can be associated with:
+
+[options="header"]
+|======
+| Name              | Description
+
+| `simulate`        | The action execution is simulated. Each action type
+                      define its own simulation operation mode. For example, the
+                      {xpack-ref}/actions-email.html[email] action creates
+                      the email that would have been sent but does not actually
+                      send it. In this mode, the action might be throttled if the
+                      current state of the watch indicates it should be.
+
+| `force_simulate`  | Similar to the the `simulate` mode, except the action is
+                      not be throttled even if the current state of the watch
+                      indicates it should be.
+
+| `execute`         | Executes the action as it would have been executed if the
+                      watch would have been triggered by its own trigger. The
+                      execution might be throttled if the current state of the
+                      watch indicates it should be.
+
+| `force_execute`   | Similar to the `execute` mode, except the action is not
+                      throttled even if the current state of the watch indicates
+                      it should be.
+
+| `skip`            | The action is skipped and is not executed or simulated.
+                      Effectively forces the action to be throttled.
+|======
+
+[float]
+==== Authorization
+You must have `manage_watcher` cluster privileges to use this API. For more
+information, see {xpack-ref}/security-privileges.html[Security Privileges].
+
+[float]
+==== Examples
+
+The following example executes the `my_watch` watch:
+
+[source,js]
+--------------------------------------------------
+POST _xpack/watcher/watch/my_watch/_execute
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:my_active_watch]
+
 The following example shows a comprehensive example of executing the `my-watch` watch:
 
 [source,js]
@@ -77,14 +154,14 @@ POST _xpack/watcher/watch/my_watch/_execute
 // TEST[setup:my_active_watch]
 <1> The triggered and schedule times are provided.
 <2> The input as defined by the watch is ignored and instead the provided input
-    will be used as the execution payload.
+    is used as the execution payload.
-<3> The condition as defined by the watch will be ignored and will be assumed to
+<3> The condition as defined by the watch is ignored and is assumed to
     evaluate to `true`.
 <4> Forces the simulation of `my-action`. Forcing the simulation means that
     throttling is ignored and the watch is simulated by {watcher} instead of
     being executed normally.
-<5> The execution of the watch will create a watch record in the watch history,
+<5> The execution of the watch creates a watch record in the watch history,
-    and the throttling state of the watch will potentially be updated accordingly.
+    and the throttling state of the watch is potentially updated accordingly.
 
 This is an example of the output:
 
@@ -192,40 +269,6 @@ This is an example of the output:
 <2> The watch record document as it would be stored in the `.watcher-history` index.
 <3> The watch execution results.
 
-[[watcher-api-execute-watch-action-mode]]
-==== Action Execution Modes
-
-Action modes define how actions are handled during the watch execution. There
-are five possible modes an action can be associated with:
-
-[options="header"]
-|======
-| Name              | Description
-
-| `simulate`        | The action execution will be simulated. Each action type
-                      define its own simulation operation mode. For example, the
-                      {xpack-ref}/actions-email.html[email] action will create
-                      the email that would have been sent but will not actually
-                      send it. In this mode, the action may be throttled if the
-                      current state of the watch indicates it should be.
-
-| `force_simulate`  | Similar to the the `simulate` mode, except the action will
-                      not be throttled even if the current state of the watch
-                      indicates it should be.
-
-| `execute`         | Executes the action as it would have been executed if the
-                      watch would have been triggered by its own trigger. The
-                      execution may be throttled if the current state of the
-                      watch indicates it should be.
-
-| `force_execute`   | Similar to the `execute` mode, except the action will not
-                      be throttled even if the current state of the watch
-                      indicates it should be.
-
-| `skip`            | The action will be skipped and won't be executed nor
-                      simulated. Effectively forcing the action to be throttled.
-|======
-
 You can set a different execution mode for every action by associating the mode
 name with the action id:
 
@@ -257,14 +300,6 @@ POST _xpack/watcher/watch/my_watch/_execute
 // CONSOLE
 // TEST[setup:my_active_watch]
 
-[float]
-[[watcher-api-execute-inline-watch]]
-==== Inline Watch Execution
-
-You can use the Execute API to execute watches that are not yet registered by
-specifying the watch definition inline. This serves as great tool for testing
-and debugging your watches prior to adding them to {watcher}.
-
 The following example shows how to execute a watch inline:
 
 [source,js]

docs/en/rest-api/watcher/get-watch.asciidoc

@@ -2,7 +2,28 @@
 [[watcher-api-get-watch]]
 === Get Watch API
 
-This API retrieves a watch by its id.
+This API retrieves a watch by its ID.
+
+[float]
+==== Request
+
+`GET _xpack/watcher/watch/<watch_id>`
+
+[float]
+==== Path Parameters
+
+`watch_id` (required)::
+  (string) Identifier for the watch.
+
+[float]
+==== Authorization
+
+You must have `manage_watcher` or `monitor_watcher` cluster privileges to use
+this API. For more information, see
+{xpack-ref}/security-privileges.html[Security Privileges].
+
+[float]
+==== Examples
 
 The following example gets a watch with `my-watch` id:
 

docs/en/rest-api/watcher/put-watch.asciidoc

@@ -3,16 +3,80 @@
 === Put Watch API
 
 The PUT watch API either registers a new watch in {watcher} or update an
-existing one. Once registered, a new document will be added to the `.watches`
+existing one.
-index, representing the watch, and its trigger will immediately be registered
+
-with the relevant trigger engine (typically the scheduler, for the `schedule`
+[float]
-trigger).
+==== Request
+
+`PUT _xpack/watcher/watch/<watch_id>`
+
+[float]
+==== Description
+
+When a watch is registered, a new document that represents the watch is added to
+the `.watches` index and its trigger is immediately registered with the relevant
+trigger engine. Typically for the `schedule` trigger, the scheduler is the
+trigger engine.
 
 IMPORTANT:  Putting a watch must be done via this API only. Do not put a watch
-            directly to the `.watches` index using Elasticsearch's Index API.
+            directly to the `.watches` index using the Elasticsearch Index API.
             If {security} is enabled, make sure no `write` privileges are
             granted to anyone over the `.watches` index.
 
+When adding a watch you can also define its initial
+{xpack-ref}/how-watcher-works.html#watch-active-state[active state]. You do that
+by setting the `active` parameter.
+
+[float]
+==== Path Parameters
+
+`watch_id` (required)::
+  (string) Identifier for the watch.
+
+[float]
+==== Query Parameters
+
+`active`::
+  (boolean) Defines whether the watch is active or inactive by default. The
+  default value is `true`, which means the watch is active by default.
+
+[float]
+==== Request Body
+
+A watch has the following fields:
+
+[options="header"]
+|======
+| Name              | Description
+
+| `trigger`         | The {xpack-ref}/trigger.html[trigger] that defines when
+                      the watch should run.
+
+| `input`           | The {xpack-ref}/input.html[input] that defines the input
+                      that loads the data for the watch.
+
+| `condition`       | The {xpack-ref}/condition.html[condition] that defines if
+                      the actions should be run.
+
+| `actions`         | The list of {xpack-ref}/actions.html[actions] that will be
+                      run if the condition matches
+
+| `metadata`        | Metadata json that will be copied into the history entries.
+
+| `throttle_period` | The minimum time between actions being run, the default
+                      for this is 5 seconds. This default can be changed in the
+                      config file with the setting `xpack.watcher.throttle.period.default_period`.
+|======
+
+[float]
+==== Authorization
+
+You must have `manage_watcher` cluster privileges to use this API. For more
+information, see {xpack-ref}/security-privileges.html[Security Privileges].
+
+[float]
+==== Examples
+
 The following example adds a watch with the `my-watch` id that has the following
 characteristics:
 
@@ -72,39 +136,10 @@ PUT _xpack/watcher/watch/my-watch
 --------------------------------------------------
 // CONSOLE
 
-A watch has the following fields:
+When you add a watch you can also define its initial
-
-[options="header"]
-|======
-| Name              | Description
-
-| `trigger`         | The {xpack-ref}/trigger.html[trigger] that defines when
-                      the watch should run.
-
-| `input`           | The {xpack-ref}/input.html[input] that defines the input
-                      that loads the data for the watch.
-
-| `condition`       | The {xpack-ref}/condition.html[condition] that defines if
-                      the actions should be run.
-
-| `actions`         | The list of {xpack-ref}/actions.html[actions] that will be
-                      run if the condition matches
-
-| `metadata`        | Metadata json that will be copied into the history entries.
-
-| `throttle_period` | The minimum time between actions being run, the default
-                      for this is 5 seconds. This default can be changed in the
-                      config file with the setting `xpack.watcher.throttle.period.default_period`.
-|======
-
-[float]
-[[watcher-api-put-watch-active-state]]
-==== Controlling Default Active State
-
-When adding a watch you can also define its initial
 {xpack-ref}/how-watcher-works.html#watch-active-state[active state]. You do that
-by setting the `active` parameter. The following command add a watch and sets it
+by setting the `active` parameter. The following command adds a watch and sets
-to be inactive by default:
+it to be inactive by default:
 
 [source,js]
 --------------------------------------------------

docs/en/rest-api/watcher/start.asciidoc

@@ -3,7 +3,20 @@
 === Start API
 
 The `start` API starts the {watcher} service if the service is not already
-running, as in the following example:
+running.
+
+[float]
+==== Request
+
+`POST _xpack/watcher/_start`
+
+==== Authorization
+
+You must have `manage_watcher` cluster privileges to use this API. For more
+information, see {xpack-ref}/security-privileges.html[Security Privileges].
+
+[float]
+==== Examples
 
 [source,js]
 --------------------------------------------------

docs/en/rest-api/watcher/stats.asciidoc

@@ -2,22 +2,70 @@
 [[watcher-api-stats]]
 === Stats API
 
-The `stats` API returns the current {watcher} metrics. You can control what
+The `stats` API returns the current {watcher} metrics.
-metrics this API returns using the `metric` parameter.
 
-The supported metrics are:
+[float]
+==== Request
 
-[options="header"]
+`GET _xpack/watcher/stats` +
-|======
-| Metric               | Description
-| `executing_watches`  | Include the current executing watches in the response.
-| `queued_watches`     | Include the watches queued for execution in the response.
-| `_all`               | Include all metrics in the response.
-|======
 
-The {watcher} `stats` API always returns basic metrics regardless of the
+`GET _xpack/watcher/stats/<metric>`
-`metric` option. The following example calls the `stats` API including the
+
-basic metrics:
+[float]
+==== Description
+
+This API always returns basic metrics. You retrieve more metrics by using
+the `metric` parameter.
+
+[float]
+===== Current executing watches metric
+
+The current executing watches metric gives insight into the watches that are
+currently being executed by {watcher}. Additional information is shared per
+watch that is currently executing. This information includes the `watch_id`,
+the time its execution started and its current execution phase.
+
+To include this metric, the `metric` option should be set to `executing_watches`
+or `_all`. In addition you can also specify the `emit_stacktraces=true`
+parameter, which adds stack traces for each watch that is being executed. These
+stack traces can give you more insight into an execution of a watch.
+
+[float]
+===== Queued watches metric
+
+{watcher} moderates the execution of watches such that their execution won't put
+too much pressure on the node and its resources. If too many watches trigger
+concurrently and there isn't enough capacity to execute them all, some of the
+watches are queued, waiting for the current executing watches to finish their
+execution. The queued watches metric gives insight on these queued watches.
+
+To include this metric, the `metric` option should include `queued_watches` or
+`_all`.
+
+[float]
+==== Path Parameters
+
+`emit_stacktraces`::
+  (boolean) Defines whether stack traces are generated for each watch that is
+  running. The default value is `false`.
+
+`metric`::
+  (enum) Defines which additional metrics are included in the response.
+  `executing_watches`::: Includes the current executing watches in the response.
+  `queued_watches`::: Includes the watches queued for execution in the response.
+  `_all`::: Includes all metrics in the response.
+
+[float]
+==== Authorization
+
+You must have `manage_watcher` or `monitor_watcher` cluster privileges to use
+this API. For more information, see
+{xpack-ref}/security-privileges.html[Security Privileges].
+
+[float]
+==== Examples
+
+The following example calls the `stats` API to retrieve basic metrics:
 
 [source,js]
 --------------------------------------------------
@@ -39,21 +87,11 @@ A successful call returns a JSON structure similar to the following example:
 }
 --------------------------------------------------
 
-<1> The current state of watcher. May be either `started`, `starting` or `stopped`.
+<1> The current state of watcher, which can be `started`, `starting`, or `stopped`.
 <2> The number of watches currently registered.
 <3> The number of watches that were triggered and currently queued for execution.
-<4> The largest size of the execution thread pool indicating the largest number
+<4> The largest size of the execution thread pool, which indicates the largest
-    of concurrent executing watches.
+number of concurrent executing watches.
-
-==== Current executing watches metric
-
-The current executing watches metric gives insight into the watches that are
-currently being executed by {watcher}. Additional information is shared per
-watch that is currently executing. This information includes the `watch_id`,
-the time its execution started and its current execution phase.
-
-To include this metric, the `metric` option should be set to `executing_watches`
-or `_all`.
 
 The following example specifies the `metric` option as a query string argument
 and will include the basic metrics and metrics about the current executing watches:
@@ -96,8 +134,8 @@ captures a watch in execution:
 }
 --------------------------------------------------
 
-<1> A list of all the Watches that are currently being executed by {watcher}.
+<1> A list of all the watches that are currently being executed by {watcher}.
-    When no watches are currently executing an empty array is returned. The
+    When no watches are currently executing, an empty array is returned. The
     captured watches are sorted by execution time in descending order. Thus the
     longest running watch is always at the top.
 <2> The id of the watch being executed.
@@ -108,21 +146,6 @@ captures a watch in execution:
 <6> The current watch execution phase. Can be `input`, `condition` `actions`,
     `awaits_execution`, `started`, `watch_transform`, `aborted`, `finished`.
 
-In addition you can also specify the `emit_stacktraces=true` parameter, which
-adds stack traces for each watch that is being executed. These stacktraces can
-give you more insight into an execution of a watch.
-
-==== Queued watches metric
-
-{watcher} moderates the execution of watches such that their execution won't put
-too much pressure on the node and its resources. If too many watches trigger
-concurrently and there isn't enough capacity to execute them all, some of the
-watches are queued, waiting for the current executing watches to finish their
-execution. The queued watches metric gives insight on these queued watches.
-
-To include this metric, the `metric` option should include `queued_watches` or
-`_all`.
-
 The following example specifies the `queued_watches` metric option and includes
 both the basic metrics and the queued watches:
 

docs/en/rest-api/watcher/stop.asciidoc

@@ -2,8 +2,21 @@
 [[watcher-api-stop]]
 === Stop API
 
-The `stop` API stops the {watcher} service if the service is running, as in the
+The `stop` API stops the {watcher} service if the service is running.
-following example:
+
+[float]
+==== Request
+
+`POST _xpack/watcher/_stop`
+
+[float]
+==== Authorization
+
+You must have `manage_watcher` cluster privileges to use this API. For more
+information, see {xpack-ref}/security-privileges.html[Security Privileges].
+
+[float]
+==== Examples
 
 [source,js]
 --------------------------------------------------