Feature/hlrc ml docs cleanup (#34316)

* HLRC: ML Add preview datafeed api

* Changing deprecation handling for parser

* Removing some duplication in docs, will address other APIs in another PR

* HLRC: ML Cleanup docs

* updating get datafeed stats docs

docs/java-rest/high-level/ml/close-job.asciidoc

@@ -1,18 +1,23 @@
-[[java-rest-high-x-pack-ml-close-job]]
+--
+:api: close-job
+:request: CloseJobRequest
+:response: CloseJobResponse
+--
+[id="{upid}-{api}"]
 === Close Job API
 
 The Close Job API provides the ability to close {ml} jobs in the cluster.
-It accepts a `CloseJobRequest` object and responds
-with a `CloseJobResponse` object.
+It accepts a +{request}+ object and responds
+with a +{response}+ object.
 
-[[java-rest-high-x-pack-ml-close-job-request]]
+[id="{upid}-{api}-request"]
 ==== Close Job Request
 
-A `CloseJobRequest` object gets created with an existing non-null `jobId`.
+A +{request}+ object gets created with an existing non-null `jobId`.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-close-job-request]
+include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
 <1> Constructing a new request referencing existing job IDs
 <2> Optionally used to close a failed job, or to forcefully close a job
@@ -22,38 +27,14 @@ which has not responded to its initial close request.
 <4> Optionally setting the `timeout` value for how long the
 execution should wait for the job to be closed.
 
-[[java-rest-high-x-pack-ml-close-job-execution]]
-==== Execution
-
-The request can be executed through the `MachineLearningClient` contained
-in the `RestHighLevelClient` object, accessed via the `machineLearningClient()` method.
+[id="{upid}-{api}-response"]
+==== Close Job Response
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-close-job-execute]
+include-tagged::{doc-tests-file}[{api}-response]
 --------------------------------------------------
-<1> `isClosed()` from the `CloseJobResponse` indicates if the job was successfully
+<1> `isClosed()` from the +{response}+ indicates if the job was successfully
 closed or not.
 
-[[java-rest-high-x-pack-ml-close-job-execution-async]]
-==== Asynchronous Execution
-
-The request can also be executed asynchronously:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-close-job-execute-async]
---------------------------------------------------
-<1> The `CloseJobRequest` to execute and the `ActionListener` to use when
-the execution completes
-
-The method does not block and returns immediately. The passed `ActionListener` is used
-to notify the caller of completion. A typical `ActionListener` for `CloseJobResponse` may
-look like
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-close-job-listener]
---------------------------------------------------
-<1> `onResponse` is called back when the action is completed successfully
-<2> `onFailure` is called back when some unexpected error occurs
+include::../execution.asciidoc[]

docs/java-rest/high-level/ml/delete-calendar.asciidoc

@@ -1,59 +1,33 @@
-[[java-rest-high-x-pack-ml-delete-calendar]]
+--
+:api: delete-calendar
+:request: DeleteCalendarRequest
+:response: AcknowledgedResponse
+--
+[id="{upid}-{api}"]
 === Delete Calendar API
 Delete a {ml} calendar.
-The API accepts a `DeleteCalendarRequest` and responds
-with a `AcknowledgedResponse` object.
+The API accepts a +{request}+ and responds
+with a +{response}+ object.
 
-[[java-rest-high-x-pack-ml-delete-calendar-request]]
+[id="{upid}-{api}-request"]
 ==== Delete Calendar Request
 
 A `DeleteCalendar` object requires a non-null `calendarId`.
 
 ["source","java",subs="attributes,callouts,macros"]
 ---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-delete-calendar-request]
+include-tagged::{doc-tests-file}[{api}-request]
 ---------------------------------------------------
 <1> Constructing a new request referencing an existing Calendar
 
-[[java-rest-high-x-pack-ml-delete-calendar-response]]
+[id="{upid}-{api}-response"]
 ==== Delete Calendar Response
 
-The returned `AcknowledgedResponse` object indicates the acknowledgement of the request:
+The returned +{response}+ object indicates the acknowledgement of the request:
 ["source","java",subs="attributes,callouts,macros"]
 ---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-delete-calendar-response]
+include-tagged::{doc-tests-file}[{api}-response]
 ---------------------------------------------------
 <1> `isAcknowledged` was the deletion request acknowledged or not
 
-[[java-rest-high-x-pack-ml-delete-calendar-execution]]
-==== Execution
-The request can be executed through the `MachineLearningClient` contained
-in the `RestHighLevelClient` object, accessed via the `machineLearningClient()` method.
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-delete-calendar-execute]
---------------------------------------------------
-
-[[java-rest-high-x-pack-ml-delete-calendar-async]]
-==== Delete Calendar Asynchronously
-
-This request can also be made asynchronously.
-["source","java",subs="attributes,callouts,macros"]
----------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-delete-calendar-execute-async]
----------------------------------------------------
-<1> The `DeleteCalendarRequest` to execute and the `ActionListener` to alert on completion or error.
-
-The deletion request returns immediately. Once the request is completed, the `ActionListener` is
-called back using the `onResponse` or `onFailure`. The latter indicates some failure occurred when
-making the request.
-
-A typical listener for a `DeleteCalendarRequest` could be defined as follows:
-
-["source","java",subs="attributes,callouts,macros"]
----------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-delete-calendar-listener]
----------------------------------------------------
-<1> The action to be taken when it is completed
-<2> What to do when a failure occurs
+include::../execution.asciidoc[]

docs/java-rest/high-level/ml/delete-datafeed.asciidoc

@@ -1,49 +1,32 @@
-[[java-rest-high-x-pack-ml-delete-datafeed]]
+--
+:api: delete-datafeed 
+:request: DeleteDatafeedRequest
+:response: AcknowledgedResponse
+--
+[id="{upid}-delete-datafeed"]
 === Delete Datafeed API
 
-[[java-rest-high-x-pack-machine-learning-delete-datafeed-request]]
+[id="{upid}-{api}-request"]
 ==== Delete Datafeed Request
 
-A `DeleteDatafeedRequest` object requires a non-null `datafeedId` and can optionally set `force`.
-Can be executed as follows:
+A +{request}+ object requires a non-null `datafeedId` and can optionally set `force`.
 
 ["source","java",subs="attributes,callouts,macros"]
 ---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-delete-ml-datafeed-request]
+include-tagged::{doc-tests-file}[{api}-request]
 ---------------------------------------------------
 <1> Use to forcefully delete a started datafeed;
 this method is quicker than stopping and deleting the datafeed.
 Defaults to `false`.
 
-[[java-rest-high-x-pack-machine-learning-delete-datafeed-response]]
+include::../execution.asciidoc[]
+
+[id="{upid}-{api}-response"]
 ==== Delete Datafeed Response
 
-The returned `AcknowledgedResponse` object indicates the acknowledgement of the request:
+The returned +{response}+ object indicates the acknowledgement of the request:
 ["source","java",subs="attributes,callouts,macros"]
 ---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-delete-ml-datafeed-response]
+include-tagged::{doc-tests-file}[{api}-response]
 ---------------------------------------------------
 <1> `isAcknowledged` was the deletion request acknowledged or not
-
-[[java-rest-high-x-pack-machine-learning-delete-datafeed-async]]
-==== Delete Datafeed Asynchronously
-
-This request can also be made asynchronously.
-["source","java",subs="attributes,callouts,macros"]
----------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-delete-ml-datafeed-request-async]
----------------------------------------------------
-<1> The `DeleteDatafeedRequest` to execute and the `ActionListener` to alert on completion or error.
-
-The deletion request returns immediately. Once the request is completed, the `ActionListener` is
-called back using the `onResponse` or `onFailure`. The latter indicates some failure occurred when
-making the request.
-
-A typical listener for a `DeleteDatafeedRequest` could be defined as follows:
-
-["source","java",subs="attributes,callouts,macros"]
----------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-delete-ml-datafeed-request-listener]
----------------------------------------------------
-<1> The action to be taken when it is completed
-<2> What to do when a failure occurs

docs/java-rest/high-level/ml/delete-forecast.asciidoc

@@ -1,20 +1,25 @@
-[[java-rest-high-x-pack-ml-delete-forecast]]
+--
+:api: delete-forecast 
+:request: DeleteForecastRequest
+:response: AcknowledgedResponse
+--
+[id="{upid}-{api}"]
 === Delete Forecast API
 
 The Delete Forecast API provides the ability to delete a {ml} job's
 forecast in the cluster.
-It accepts a `DeleteForecastRequest` object and responds
-with an `AcknowledgedResponse` object.
+It accepts a +{request}+ object and responds
+with an +{response}+ object.
 
-[[java-rest-high-x-pack-ml-delete-forecast-request]]
+[id="{upid}-{api}-request"]
 ==== Delete Forecast Request
 
-A `DeleteForecastRequest` object gets created with an existing non-null `jobId`.
+A +{request}+ object gets created with an existing non-null `jobId`.
 All other fields are optional for the request.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-delete-forecast-request]
+include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
 <1> Constructing a new request referencing an existing `jobId`
 
@@ -24,55 +29,23 @@ The following arguments are optional.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-delete-forecast-request-options]
+include-tagged::{doc-tests-file}[{api}-request-options]
 --------------------------------------------------
 <1> Sets the specific forecastIds to delete, can be set to `_all` to indicate ALL forecasts for the given
 `jobId` 
 <2> Set the timeout for the request to respond, default is 30 seconds 
 <3> Set the `allow_no_forecasts` option. When `true` no error will be returned if an `_all`
-request finds no forecasts. It defaults to `true` 
+request finds no forecasts. It defaults to `true`
 
-[[java-rest-high-x-pack-ml-delete-forecast-execution]]
-==== Execution
-
-The request can be executed through the `MachineLearningClient` contained
-in the `RestHighLevelClient` object, accessed via the `machineLearningClient()` method.
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-delete-forecast-execute]
---------------------------------------------------
-
-[[java-rest-high-x-pack-ml-delete-forecast-execution-async]]
-==== Asynchronous Execution
-
-The request can also be executed asynchronously:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-delete-forecast-execute-async]
---------------------------------------------------
-<1> The `DeleteForecastRequest` to execute and the `ActionListener` to use when
-the execution completes
-
-The method does not block and returns immediately. The passed `ActionListener` is used
-to notify the caller of completion. A typical `ActionListener` for `AcknowledgedResponse` may
-look like
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-delete-forecast-listener]
---------------------------------------------------
-<1> `onResponse` is called back when the action is completed successfully
-<2> `onFailure` is called back when some unexpected error occurs
-
-[[java-rest-high-x-pack-ml-delete-forecast-response]]
+[id="{upid}-{api}-response"]
 ==== Delete Forecast Response
 
-An `AcknowledgedResponse` contains an acknowledgement of the forecast(s) deletion
+An +{response}+ contains an acknowledgement of the forecast(s) deletion
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-delete-forecast-response]
+include-tagged::{doc-tests-file}[{api}-response]
 --------------------------------------------------
 <1> `isAcknowledged()` indicates if the forecast was successfully deleted or not.
+
+include::../execution.asciidoc[]

docs/java-rest/high-level/ml/delete-job.asciidoc

@@ -1,14 +1,19 @@
-[[java-rest-high-x-pack-ml-delete-job]]
+--
+:api: delete-job 
+:request: DeleteJobRequest
+:response: AcknowledgedResponse
+--
+[id="{upid}-{api}"]
 === Delete Job API
 
-[[java-rest-high-x-pack-machine-learning-delete-job-request]]
+[id="{upid}-{api}-request"]
 ==== Delete Job Request
 
-A `DeleteJobRequest` object requires a non-null `jobId`.
+A +{request}+ object requires a non-null `jobId` and can optionally set `force`.
 
 ["source","java",subs="attributes,callouts,macros"]
 ---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-delete-ml-job-request]
+include-tagged::{doc-tests-file}[{api}-request]
 ---------------------------------------------------
 <1> Constructing a new request referencing an existing `jobId`
 
@@ -18,7 +23,7 @@ The following arguments are optional:
 
 ["source","java",subs="attributes,callouts,macros"]
 ---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-delete-ml-job-request-force]
+include-tagged::{doc-tests-file}[{api}-request-force]
 ---------------------------------------------------
 <1> Use to forcefully delete an opened job;
 this method is quicker than closing and deleting the job.
@@ -26,55 +31,23 @@ Defaults to `false`.
 
 ["source","java",subs="attributes,callouts,macros"]
 ---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-delete-ml-job-request-wait-for-completion]
+include-tagged::{doc-tests-file}[{api}-request-wait-for-completion]
 ---------------------------------------------------
 <1> Use to set whether the request should wait until the operation has completed before returning.
 Defaults to `true`.
 
-[[java-rest-high-x-pack-machine-learning-delete-job-execution]]
-==== Execution
 
-The request can be executed through the `MachineLearningClient` contained
-in the `RestHighLevelClient` object, accessed via the `machineLearningClient()` method.
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-delete-ml-job-execute]
---------------------------------------------------
-
-[[java-rest-high-x-pack-machine-learning-delete-job-response]]
+[id="{upid}-{api}-response"]
 ==== Delete Job Response
 
-The returned `DeleteJobResponse` object contains the acknowledgement of the
-job deletion or the deletion task depending on whether the request was set
-to wait for completion:
+The returned +{response}+ object indicates the acknowledgement of the job deletion or
+the deletion task depending on whether the request was set to wait for completion:
 
 ["source","java",subs="attributes,callouts,macros"]
 ---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-delete-ml-job-response]
+include-tagged::{doc-tests-file}[{api}-response]
 ---------------------------------------------------
 <1> whether was job deletion was acknowledged or not; will be `null` when set not to wait for completion
 <2> the id of the job deletion task; will be `null` when set to wait for completion
 
-[[java-rest-high-x-pack-machine-learning-delete-job-async]]
-==== Delete Job Asynchronously
-
-This request can also be made asynchronously.
-["source","java",subs="attributes,callouts,macros"]
----------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-delete-ml-job-request-async]
----------------------------------------------------
-<1> The `DeleteJobRequest` to execute and the `ActionListener` to alert on completion or error.
-
-The deletion request returns immediately. Once the request is completed, the `ActionListener` is
-called back using the `onResponse` or `onFailure`. The latter indicates some failure occurred when
-making the request.
-
-A typical listener for a `DeleteJobRequest` could be defined as follows:
-
-["source","java",subs="attributes,callouts,macros"]
----------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-delete-ml-job-request-listener]
----------------------------------------------------
-<1> The action to be taken when it is completed
-<2> What to do when a failure occurs
+include::../execution.asciidoc[]

docs/java-rest/high-level/ml/flush-job.asciidoc

@@ -1,20 +1,25 @@
-[[java-rest-high-x-pack-ml-flush-job]]
+--
+:api: flush-job
+:request: FlushJobRequest
+:response: FlushJobResponse
+--
+[id="{upid}-{api}"]
 === Flush Job API
 
 The Flush Job API provides the ability to flush a {ml} job's 
 datafeed in the cluster.
-It accepts a `FlushJobRequest` object and responds
-with a `FlushJobResponse` object.
+It accepts a +{request}+ object and responds
+with a +{response}+ object.
 
-[[java-rest-high-x-pack-ml-flush-job-request]]
+[id="{upid}-{api}-request"]
 ==== Flush Job Request
 
-A `FlushJobRequest` object gets created with an existing non-null `jobId`.
+A +{request}+ object gets created with an existing non-null `jobId`.
 All other fields are optional for the request.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-flush-job-request]
+include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
 <1> Constructing a new request referencing an existing `jobId`
 
@@ -24,7 +29,7 @@ The following arguments are optional.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-flush-job-request-options]
+include-tagged::{doc-tests-file}[{api}-request-options]
 --------------------------------------------------
 <1> Set request to calculate the interim results
 <2> Set the advanced time to flush to the particular time value
@@ -34,50 +39,18 @@ to calculate the interim results (requires `calc_interim` to be `true`)
 to calculate interim results (requires `calc_interim` to be `true`)
 <5> Set the skip time to skip a particular time value
 
-[[java-rest-high-x-pack-ml-flush-job-execution]]
-==== Execution
-
-The request can be executed through the `MachineLearningClient` contained
-in the `RestHighLevelClient` object, accessed via the `machineLearningClient()` method.
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-flush-job-execute]
---------------------------------------------------
-
-[[java-rest-high-x-pack-ml-flush-job-execution-async]]
-==== Asynchronous Execution
-
-The request can also be executed asynchronously:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-flush-job-execute-async]
---------------------------------------------------
-<1> The `FlushJobRequest` to execute and the `ActionListener` to use when
-the execution completes
-
-The method does not block and returns immediately. The passed `ActionListener` is used
-to notify the caller of completion. A typical `ActionListener` for `FlushJobResponse` may
-look like
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-flush-job-listener]
---------------------------------------------------
-<1> `onResponse` is called back when the action is completed successfully
-<2> `onFailure` is called back when some unexpected error occurs
-
-[[java-rest-high-x-pack-ml-flush-job-response]]
+[id="{upid}-{api}-response"]
 ==== Flush Job Response
 
-A `FlushJobResponse` contains an acknowledgement and an optional end date for the
+A +{response}+ contains an acknowledgement and an optional end date for the
 last finalized bucket
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-flush-job-response]
+include-tagged::{doc-tests-file}[{api}-response]
 --------------------------------------------------
 <1> `isFlushed()` indicates if the job was successfully flushed or not.
 <2> `getLastFinalizedBucketEnd()` provides the timestamp
-(in milliseconds-since-the-epoch) of the end of the last bucket that was processed.
+(in milliseconds-since-the-epoch) of the end of the last bucket that was processed.
+
+include::../execution.asciidoc[]

docs/java-rest/high-level/ml/forecast-job.asciidoc

@@ -1,20 +1,25 @@
-[[java-rest-high-x-pack-ml-forecast-job]]
+--
+:api: forecast-job 
+:request: ForecastJobRequest
+:response: ForecastJobResponse
+--
+[id="{upid}-{api}"]
 === Forecast Job API
 
 The Forecast Job API provides the ability to forecast a {ml} job's behavior based
 on historical data.
-It accepts a `ForecastJobRequest` object and responds
-with a `ForecastJobResponse` object.
+It accepts a +{request}+ object and responds
+with a +{response}+ object.
 
-[[java-rest-high-x-pack-ml-forecast-job-request]]
+[id="{upid}-{api}-request"]
 ==== Forecast Job Request
 
-A `ForecastJobRequest` object gets created with an existing non-null `jobId`.
+A +{request}+ object gets created with an existing non-null `jobId`.
 All other fields are optional for the request.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-forecast-job-request]
+include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
 <1> Constructing a new request referencing an existing `jobId`
 
@@ -24,53 +29,21 @@ The following arguments are optional.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-forecast-job-request-options]
+include-tagged::{doc-tests-file}[{api}-request-options]
 --------------------------------------------------
 <1> Set when the forecast for the job should expire
 <2> Set how far into the future should the forecast predict
 
-[[java-rest-high-x-pack-ml-forecast-job-execution]]
-==== Execution
-
-The request can be executed through the `MachineLearningClient` contained
-in the `RestHighLevelClient` object, accessed via the `machineLearningClient()` method.
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-forecast-job-execute]
---------------------------------------------------
-
-[[java-rest-high-x-pack-ml-forecast-job-execution-async]]
-==== Asynchronous Execution
-
-The request can also be executed asynchronously:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-forecast-job-execute-async]
---------------------------------------------------
-<1> The `ForecastJobRequest` to execute and the `ActionListener` to use when
-the execution completes
-
-The method does not block and returns immediately. The passed `ActionListener` is used
-to notify the caller of completion. A typical `ActionListener` for `ForecastJobResponse` may
-look like
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-forecast-job-listener]
---------------------------------------------------
-<1> `onResponse` is called back when the action is completed successfully
-<2> `onFailure` is called back when some unexpected error occurs
-
-[[java-rest-high-x-pack-ml-forecast-job-response]]
+[id="{upid}-{api}-response"]
 ==== Forecast Job Response
 
-A `ForecastJobResponse` contains an acknowledgement and the forecast ID
+A +{response}+ contains an acknowledgement and the forecast ID
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-forecast-job-response]
+include-tagged::{doc-tests-file}[{api}-response]
 --------------------------------------------------
 <1> `isAcknowledged()` indicates if the forecast was successful
-<2> `getForecastId()` provides the ID of the forecast that was created
+<2> `getForecastId()` provides the ID of the forecast that was created
+
+include::../execution.asciidoc[]

docs/java-rest/high-level/ml/get-buckets.asciidoc

@@ -1,18 +1,23 @@
-[[java-rest-high-x-pack-ml-get-buckets]]
+--
+:api: get-buckets 
+:request: GetBucketsRequest
+:response: GetBucketsResponse
+--
+[id="{upid}-{api}"]
 === Get Buckets API
 
 The Get Buckets API retrieves one or more bucket results.
-It accepts a `GetBucketsRequest` object and responds
-with a `GetBucketsResponse` object.
+It accepts a +{request}+ object and responds
+with a +{response}+ object.
 
-[[java-rest-high-x-pack-ml-get-buckets-request]]
+[id="{upid}-{api}-request"]
 ==== Get Buckets Request
 
-A `GetBucketsRequest` object gets created with an existing non-null `jobId`.
+A +{request}+ object gets created with an existing non-null `jobId`.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-buckets-request]
+include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
 <1> Constructing a new request referencing an existing `jobId`
 
@@ -21,105 +26,69 @@ The following arguments are optional:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-buckets-timestamp]
+include-tagged::{doc-tests-file}[{api}-timestamp]
 --------------------------------------------------
 <1> The timestamp of the bucket to get. Otherwise it will return all buckets.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-buckets-anomaly-score]
+include-tagged::{doc-tests-file}[{api}-anomaly-score]
 --------------------------------------------------
 <1> Buckets with anomaly scores greater or equal than this value will be returned.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-buckets-desc]
+include-tagged::{doc-tests-file}[{api}-desc]
 --------------------------------------------------
 <1> If `true`, the buckets are sorted in descending order. Defaults to `false`.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-buckets-end]
+include-tagged::{doc-tests-file}[{api}-end]
 --------------------------------------------------
 <1> Buckets with timestamps earlier than this time will be returned.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-buckets-exclude-interim]
+include-tagged::{doc-tests-file}[{api}-exclude-interim]
 --------------------------------------------------
 <1> If `true`, interim results will be excluded. Defaults to `false`.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-buckets-expand]
+include-tagged::{doc-tests-file}[{api}-expand]
 --------------------------------------------------
 <1> If `true`, buckets will include their anomaly records. Defaults to `false`.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-buckets-page]
+include-tagged::{doc-tests-file}[{api}-page]
 --------------------------------------------------
 <1> The page parameters `from` and `size`. `from` specifies the number of buckets to skip.
 `size` specifies the maximum number of buckets to get. Defaults to `0` and `100` respectively.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-buckets-sort]
+include-tagged::{doc-tests-file}[{api}-sort]
 --------------------------------------------------
 <1> The field to sort buckets on. Defaults to `timestamp`.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-buckets-start]
+include-tagged::{doc-tests-file}[{api}-start]
 --------------------------------------------------
 <1> Buckets with timestamps on or after this time will be returned.
 
-[[java-rest-high-x-pack-ml-get-buckets-execution]]
-==== Execution
+include::../execution.asciidoc[]
 
-The request can be executed through the `MachineLearningClient` contained
-in the `RestHighLevelClient` object, accessed via the `machineLearningClient()` method.
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-buckets-execute]
---------------------------------------------------
-
-
-[[java-rest-high-x-pack-ml-get-buckets-execution-async]]
-==== Asynchronous Execution
-
-The request can also be executed asynchronously:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-buckets-execute-async]
---------------------------------------------------
-<1> The `GetBucketsRequest` to execute and the `ActionListener` to use when
-the execution completes
-
-The asynchronous method does not block and returns immediately. Once it is
-completed the `ActionListener` is called back with the `onResponse` method
-if the execution is successful or the `onFailure` method if the execution
-failed.
-
-A typical listener for `GetBucketsResponse` looks like:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-buckets-listener]
---------------------------------------------------
-<1> `onResponse` is called back when the action is completed successfully
-<2> `onFailure` is called back when some unexpected error occurs
-
-[[java-rest-high-x-pack-ml-get-buckets-response]]
+[id="{upid}-{api}-response"]
 ==== Get Buckets Response
 
-The returned `GetBucketsResponse` contains the requested buckets:
+The returned +{response}+ contains the requested buckets:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-buckets-response]
+include-tagged::{doc-tests-file}[{api}-response]
 --------------------------------------------------
 <1> The count of buckets that were matched
 <2> The buckets retrieved

docs/java-rest/high-level/ml/get-calendars.asciidoc

@@ -1,83 +1,53 @@
-[[java-rest-high-x-pack-ml-get-calendars]]
+--
+:api: get-calendars 
+:request: GetCalendarsRequest
+:response: GetCalendarsResponse
+--
+[id="{upid}-{api}"]
 === Get Calendars API
 Retrieves one or more calendar objects.
-It accepts a `GetCalendarsRequest` and responds
-with a `GetCalendarsResponse` object.
+It accepts a +{request}+ and responds
+with a +{response}+ object.
 
-[[java-rest-high-x-pack-ml-get-calendars-request]]
+[id="{upid}-{api}-request"]
 ==== Get Calendars Request
 
-By default a `GetCalendarsRequest` with no calendar Id set will return all
+By default a +{request}+ with no calendar Id set will return all
 calendars. Using the literal `_all` also returns all calendars.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-calendars-request]
+include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
 <1> Constructing a new request for all calendars
 
-
 ==== Optional Arguments
 The following arguments are optional:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-calendars-id]
+include-tagged::{doc-tests-file}[{api}-id]
 --------------------------------------------------
 <1> Construct a request for the single calendar `holidays`
 
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-calendars-page]
+include-tagged::{doc-tests-file}[{api}-page]
 --------------------------------------------------
 <1> The page parameters `from` and `size`. `from` specifies the number of calendars to skip.
 `size` specifies the maximum number of calendars to get. Defaults to `0` and `100` respectively.
 
-[[java-rest-high-x-pack-ml-get-calendars-execution]]
-==== Execution
-The request can be executed through the `MachineLearningClient` contained
-in the `RestHighLevelClient` object, accessed via the `machineLearningClient()` method.
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-calendars-execution]
---------------------------------------------------
-
-[[java-rest-high-x-pack-ml-get-calendars-execution-async]]
-==== Asynchronous Execution
-
-The request can also be executed asynchronously:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-calendars-execute-async]
---------------------------------------------------
-<1> The `GetCalendarsRequest` to execute and the `ActionListener` to use when
-the execution completes
-
-The asynchronous method does not block and returns immediately. Once it is
-completed the `ActionListener` is called back with the `onResponse` method
-if the execution is successful or the `onFailure` method if the execution
-failed.
-
-A typical listener for `GetCalendarsResponse` looks like:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-calendars-listener]
---------------------------------------------------
-<1> `onResponse` is called back when the action is completed successfully
-<2> `onFailure` is called back when some unexpected error occurs
+include::../execution.asciidoc[]
 
-[[java-rest-high-x-pack-ml-get-calendars-response]]
+[id="{upid}-{api}-response"]
 ==== Get calendars Response
 
-The returned `GetCalendarsResponse` contains the requested calendars:
+The returned +{response}+ contains the requested calendars:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-calendars-response]
+include-tagged::{doc-tests-file}[{api}-response]
 --------------------------------------------------
 <1> The count of calendars that were matched
 <2> The calendars retrieved

docs/java-rest/high-level/ml/get-categories.asciidoc

@@ -1,18 +1,23 @@
-[[java-rest-high-x-pack-ml-get-categories]]
+--
+:api: get-categories
+:request: GetCategoriesRequest
+:response: GetCategoriesResponse
+--
+[id="{upid}-{api}"]
 === Get Categories API
 
 The Get Categories API retrieves one or more category results.
-It accepts a `GetCategoriesRequest` object and responds
-with a `GetCategoriesResponse` object.
+It accepts a +{request}+ object and responds
+with a +{response}+ object.
 
-[[java-rest-high-x-pack-ml-get-categories-request]]
+[id="{upid}-{api}-request"]
 ==== Get Categories Request
 
-A `GetCategoriesRequest` object gets created with an existing non-null `jobId`.
+A +{request}+ object gets created with an existing non-null `jobId`.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-categories-request]
+include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
 <1> Constructing a new request referencing an existing `jobId`
 
@@ -21,63 +26,27 @@ The following arguments are optional:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-categories-category-id]
+include-tagged::{doc-tests-file}[{api}-category-id]
 --------------------------------------------------
 <1> The id of the category to get. Otherwise it will return all categories.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-categories-page]
+include-tagged::{doc-tests-file}[{api}-page]
 --------------------------------------------------
 <1> The page parameters `from` and `size`. `from` specifies the number of categories to skip.
 `size` specifies the maximum number of categories to get. Defaults to `0` and `100` respectively.
 
-[[java-rest-high-x-pack-ml-get-categories-execution]]
-==== Execution
+include::../execution.asciidoc[]
 
-The request can be executed through the `MachineLearningClient` contained
-in the `RestHighLevelClient` object, accessed via the `machineLearningClient()` method.
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-categories-execute]
---------------------------------------------------
-
-
-[[java-rest-high-x-pack-ml-get-categories-execution-async]]
-==== Asynchronous Execution
-
-The request can also be executed asynchronously:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-categories-execute-async]
---------------------------------------------------
-<1> The `GetCategoriesRequest` to execute and the `ActionListener` to use when
-the execution completes
-
-The asynchronous method does not block and returns immediately. Once it is
-completed the `ActionListener` is called back with the `onResponse` method
-if the execution is successful or the `onFailure` method if the execution
-failed.
-
-A typical listener for `GetCategoriesResponse` looks like:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-categories-listener]
---------------------------------------------------
-<1> `onResponse` is called back when the action is completed successfully
-<2> `onFailure` is called back when some unexpected error occurs
-
-[[java-rest-high-x-pack-ml-get-categories-response]]
+[id="{upid}-{api}-response"]
 ==== Get Categories Response
 
-The returned `GetCategoriesResponse` contains the requested categories:
+The returned +{response}+ contains the requested categories:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-categories-response]
+include-tagged::{doc-tests-file}[{api}-response]
 --------------------------------------------------
 <1> The count of categories that were matched
 <2> The categories retrieved

docs/java-rest/high-level/ml/get-datafeed-stats.asciidoc

@@ -1,67 +1,40 @@
-[[java-rest-high-x-pack-ml-get-datafeed-stats]]
+--
+:api: get-datafeed-stats
+:request: GetDatafeedStatsRequest
+:response: GetDatafeedStatsResponse
+--
+[id="{upid}-{api}"]
 === Get Datafeed Stats API
 
 The Get Datafeed Stats API provides the ability to get any number of
  {ml} datafeed's statistics in the cluster.
-It accepts a `GetDatafeedStatsRequest` object and responds
-with a `GetDatafeedStatsResponse` object.
+It accepts a +{request}+ object and responds
+with a +{response}+ object.
 
-[[java-rest-high-x-pack-ml-get-datafeed-stats-request]]
+[id="{upid}-{api}-request"]
 ==== Get Datafeed Stats Request
 
-A `GetDatafeedStatsRequest` object can have any number of `datafeedId`
+A +{request}+ object can have any number of `datafeedId`
 entries. However, they all must be non-null. An empty list is the same as
 requesting statistics for all datafeeds.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-datafeed-stats-request]
+include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
 <1> Constructing a new request referencing existing `datafeedIds`, can contain wildcards
 <2> Whether to ignore if a wildcard expression matches no datafeeds.
  (This includes `_all` string or when no datafeeds have been specified)
 
-[[java-rest-high-x-pack-ml-get-datafeed-stats-execution]]
-==== Execution
+include::../execution.asciidoc[]
 
-The request can be executed through the `MachineLearningClient` contained
-in the `RestHighLevelClient` object, accessed via the `machineLearningClient()` method.
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-datafeed-stats-execute]
---------------------------------------------------
-
-[[java-rest-high-x-pack-ml-get-datafeed-stats-execution-async]]
-==== Asynchronous Execution
-
-The request can also be executed asynchronously:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-datafeed-stats-execute-async]
---------------------------------------------------
-<1> The `GetDatafeedStatsRequest` to execute and the `ActionListener` to use when
-the execution completes
-
-The method does not block and returns immediately. The passed `ActionListener` is used
-to notify the caller of completion. A typical `ActionListener` for `GetDatafeedStatsResponse` may
-look like
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-datafeed-stats-listener]
---------------------------------------------------
-<1> `onResponse` is called back when the action is completed successfully
-<2> `onFailure` is called back when some unexpected error occurs
-
-[[java-rest-high-x-pack-ml-get-datafeed-stats-response]]
+[id="{upid}-{api}-response"]
 ==== Get Datafeed Stats Response
-The returned `GetDatafeedStatsResponse` contains the requested datafeed statistics:
+The returned +{response}+ contains the requested datafeed statistics:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-datafeed-stats-response]
+include-tagged::{doc-tests-file}[{api}-response]
 --------------------------------------------------
 <1> `count()` indicates the number of datafeeds statistics found
 <2> `datafeedStats()` is the collection of {ml} `DatafeedStats` objects found

docs/java-rest/high-level/ml/get-datafeed.asciidoc

@@ -1,56 +1,37 @@
-[[java-rest-high-x-pack-ml-get-datafeed]]
+--
+:api: get-datafeed
+:request: GetDatafeedRequest
+:response: GetDatafeedResponse
+--
+[id="{upid}-{api}"]
 === Get Datafeed API
 
 The Get Datafeed API provides the ability to get {ml} datafeeds in the cluster.
-It accepts a `GetDatafeedRequest` object and responds
-with a `GetDatafeedResponse` object.
+It accepts a +{request}+ object and responds
+with a +{response}+ object.
 
-[[java-rest-high-x-pack-ml-get-datafeed-request]]
+[id="{upid}-{api}-request"]
 ==== Get Datafeed Request
 
-A `GetDatafeedRequest` object gets can have any number of `datafeedId` entries.
+A +{request}+ object gets can have any number of `datafeedId` entries.
 However, they all must be non-null. An empty list is the same as requesting for all datafeeds.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-datafeed-request]
+include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
 <1> Constructing a new request referencing existing `datafeedIds`, can contain wildcards
 <2> Whether to ignore if a wildcard expression matches no datafeeds.
  (This includes `_all` string or when no datafeeds have been specified)
 
-[[java-rest-high-x-pack-ml-get-datafeed-execution]]
-==== Execution
-
-The request can be executed through the `MachineLearningClient` contained
-in the `RestHighLevelClient` object, accessed via the `machineLearningClient()` method.
+[id="{upid}-{api}-response"]
+==== Get Datafeed Response
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-datafeed-execute]
+include-tagged::{doc-tests-file}[{api}-response]
 --------------------------------------------------
 <1> The count of retrieved datafeeds
 <2> The retrieved datafeeds
 
-[[java-rest-high-x-pack-ml-get-datafeed-execution-async]]
-==== Asynchronous Execution
-
-The request can also be executed asynchronously:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-datafeed-execute-async]
---------------------------------------------------
-<1> The `GetDatafeedRequest` to execute and the `ActionListener` to use when
-the execution completes
-
-The method does not block and returns immediately. The passed `ActionListener` is used
-to notify the caller of completion. A typical `ActionListener` for `GetDatafeedResponse` may
-look like
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-datafeed-listener]
---------------------------------------------------
-<1> `onResponse` is called back when the action is completed successfully
-<2> `onFailure` is called back when some unexpected error occurs
+include::../execution.asciidoc[]

docs/java-rest/high-level/ml/get-influencers.asciidoc

@@ -1,18 +1,23 @@
-[[java-rest-high-x-pack-ml-get-influencers]]
+--
+:api: get-influencers
+:request: GetInfluencersRequest
+:response: GetInfluencersResponse
+--
+[id="{upid}-{api}"]
 === Get Influencers API
 
 The Get Influencers API retrieves one or more influencer results.
-It accepts a `GetInfluencersRequest` object and responds
-with a `GetInfluencersResponse` object.
+It accepts a +{request}+ object and responds
+with a +{response}+ object.
 
-[[java-rest-high-x-pack-ml-get-influencers-request]]
+[id="{upid}-{api}-request"]
 ==== Get Influencers Request
 
-A `GetInfluencersRequest` object gets created with an existing non-null `jobId`.
+A +{request}+ object gets created with an existing non-null `jobId`.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-influencers-request]
+include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
 <1> Constructing a new request referencing an existing `jobId`
 
@@ -21,92 +26,57 @@ The following arguments are optional:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-influencers-desc]
+include-tagged::{doc-tests-file}[{api}-desc]
 --------------------------------------------------
 <1> If `true`, the influencers are sorted in descending order. Defaults to `false`.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-influencers-end]
+include-tagged::{doc-tests-file}[{api}-end]
 --------------------------------------------------
 <1> Influencers with timestamps earlier than this time will be returned.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-influencers-exclude-interim]
+include-tagged::{doc-tests-file}[{api}-exclude-interim]
 --------------------------------------------------
 <1> If `true`, interim results will be excluded. Defaults to `false`.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-influencers-influencer-score]
+include-tagged::{doc-tests-file}[{api}-influencer-score]
 --------------------------------------------------
 <1> Influencers with influencer_score greater or equal than this value will be returned.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-influencers-page]
+include-tagged::{doc-tests-file}[{api}-page]
 --------------------------------------------------
 <1> The page parameters `from` and `size`. `from` specifies the number of influencers to skip.
 `size` specifies the maximum number of influencers to get. Defaults to `0` and `100` respectively.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-influencers-sort]
+include-tagged::{doc-tests-file}[{api}-sort]
 --------------------------------------------------
 <1> The field to sort influencers on. Defaults to `influencer_score`.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-influencers-start]
+include-tagged::{doc-tests-file}[{api}-start]
 --------------------------------------------------
 <1> Influencers with timestamps on or after this time will be returned.
 
-[[java-rest-high-x-pack-ml-get-influencers-execution]]
-==== Execution
+include::../execution.asciidoc[]
 
-The request can be executed through the `MachineLearningClient` contained
-in the `RestHighLevelClient` object, accessed via the `machineLearningClient()` method.
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-influencers-execute]
---------------------------------------------------
-
-[[java-rest-high-x-pack-ml-get-influencers-execution-async]]
-==== Asynchronous Execution
-
-The request can also be executed asynchronously:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-influencers-execute-async]
---------------------------------------------------
-<1> The `GetInfluencersRequest` to execute and the `ActionListener` to use when
-the execution completes
-
-The asynchronous method does not block and returns immediately. Once it is
-completed the `ActionListener` is called back with the `onResponse` method
-if the execution is successful or the `onFailure` method if the execution
-failed.
-
-A typical listener for `GetInfluencersResponse` looks like:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-influencers-listener]
---------------------------------------------------
-<1> `onResponse` is called back when the action is completed successfully
-<2> `onFailure` is called back when some unexpected error occurs
-
-[[java-rest-high-x-pack-ml-get-influencers-response]]
+[id="{upid}-{api}-response"]
 ==== Get Influencers Response
 
-The returned `GetInfluencersResponse` contains the requested influencers:
+The returned +{response}+ contains the requested influencers:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-influencers-response]
+include-tagged::{doc-tests-file}[{api}-response]
 --------------------------------------------------
 <1> The count of influencers that were matched
 <2> The influencers retrieved

docs/java-rest/high-level/ml/get-job-stats.asciidoc

@@ -1,12 +1,17 @@
-[[java-rest-high-x-pack-ml-get-job-stats]]
+--
+:api: get-job-stats
+:request: GetJobStatsRequest
+:response: GetJobStatsResponse
+--
+[id="{upid}-{api}"]
 === Get Job Stats API
 
 The Get Job Stats API provides the ability to get any number of
  {ml} job's statistics in the cluster.
-It accepts a `GetJobStatsRequest` object and responds
-with a `GetJobStatsResponse` object.
+It accepts a +{request}+ object and responds
+with a +{response}+ object.
 
-[[java-rest-high-x-pack-ml-get-job-stats-request]]
+[id="{upid}-{api}-request"]
 ==== Get Job Stats Request
 
 A `GetJobsStatsRequest` object can have any number of `jobId`
@@ -15,53 +20,21 @@ requesting statistics for all jobs.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-job-stats-request]
+include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
 <1> Constructing a new request referencing existing `jobIds`, can contain wildcards
 <2> Whether to ignore if a wildcard expression matches no jobs.
  (This includes `_all` string or when no jobs have been specified)
 
-[[java-rest-high-x-pack-ml-get-job-stats-execution]]
-==== Execution
+include::../execution.asciidoc[]
 
-The request can be executed through the `MachineLearningClient` contained
-in the `RestHighLevelClient` object, accessed via the `machineLearningClient()` method.
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-job-stats-execute]
---------------------------------------------------
-
-[[java-rest-high-x-pack-ml-get-job-stats-execution-async]]
-==== Asynchronous Execution
-
-The request can also be executed asynchronously:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-job-stats-execute-async]
---------------------------------------------------
-<1> The `GetJobsStatsRequest` to execute and the `ActionListener` to use when
-the execution completes
-
-The method does not block and returns immediately. The passed `ActionListener` is used
-to notify the caller of completion. A typical `ActionListener` for `GetJobsStatsResponse` may
-look like
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-job-stats-listener]
---------------------------------------------------
-<1> `onResponse` is called back when the action is completed successfully
-<2> `onFailure` is called back when some unexpected error occurs
-
-[[java-rest-high-x-pack-ml-get-job-stats-response]]
+[id="{upid}-{api}-response"]
 ==== Get Job Stats Response
-The returned `GetJobStatsResponse` contains the requested job statistics:
+The returned +{response}+ contains the requested job statistics:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-job-stats-response]
+include-tagged::{doc-tests-file}[{api}-response]
 --------------------------------------------------
 <1> `getCount()` indicates the number of jobs statistics found
 <2> `getJobStats()` is the collection of {ml} `JobStats` objects found

docs/java-rest/high-level/ml/get-job.asciidoc

@@ -1,57 +1,38 @@
-[[java-rest-high-x-pack-ml-get-job]]
+--
+:api: get-job
+:request: GetJobRequest
+:response: GetJobResponse
+--
+[id="{upid}-{api}"]
 === Get Job API
 
 The Get Job API provides the ability to get {ml} jobs in the cluster.
-It accepts a `GetJobRequest` object and responds
-with a `GetJobResponse` object.
+It accepts a +{request}+ object and responds
+with a +{response}+ object.
 
-[[java-rest-high-x-pack-ml-get-job-request]]
+[id="{upid}-{api}-request"]
 ==== Get Job Request
 
-A `GetJobRequest` object gets can have any number of `jobId` or `groupName`
+A +{request}+ object gets can have any number of `jobId` or `groupName`
 entries. However, they all must be non-null. An empty list is the same as
 requesting for all jobs.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-job-request]
+include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
 <1> Constructing a new request referencing existing `jobIds`, can contain wildcards
 <2> Whether to ignore if a wildcard expression matches no jobs.
  (This includes `_all` string or when no jobs have been specified)
 
-[[java-rest-high-x-pack-ml-get-job-execution]]
-==== Execution
-
-The request can be executed through the `MachineLearningClient` contained
-in the `RestHighLevelClient` object, accessed via the `machineLearningClient()` method.
+[id="{upid}-{api}-response"]
+==== Get Job Response
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-job-execute]
+include-tagged::{doc-tests-file}[{api}-response]
 --------------------------------------------------
-<1> `getCount()` from the `GetJobResponse` indicates the number of jobs found
+<1> `getCount()` from the +{response}+ indicates the number of jobs found
 <2> `getJobs()` is the collection of {ml} `Job` objects found
 
-[[java-rest-high-x-pack-ml-get-job-execution-async]]
-==== Asynchronous Execution
-
-The request can also be executed asynchronously:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-job-execute-async]
---------------------------------------------------
-<1> The `GetJobRequest` to execute and the `ActionListener` to use when
-the execution completes
-
-The method does not block and returns immediately. The passed `ActionListener` is used
-to notify the caller of completion. A typical `ActionListener` for `GetJobResponse` may
-look like
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-job-listener]
---------------------------------------------------
-<1> `onResponse` is called back when the action is completed successfully
-<2> `onFailure` is called back when some unexpected error occurs
+include::../execution.asciidoc[]

docs/java-rest/high-level/ml/get-overall-buckets.asciidoc

@@ -1,19 +1,24 @@
-[[java-rest-high-x-pack-ml-get-overall-buckets]]
+--
+:api: get-overall-buckets
+:request: GetOverallBucketsRequest
+:response: GetOverallBucketsResponse
+--
+[id="{upid}-{api}"]
 === Get Overall Buckets API
 
 The Get Overall Buckets API retrieves overall bucket results that
 summarize the bucket results of multiple jobs.
-It accepts a `GetOverallBucketsRequest` object and responds
-with a `GetOverallBucketsResponse` object.
+It accepts a +{request}+ object and responds
+with a +{response}+ object.
 
-[[java-rest-high-x-pack-ml-get-overall-buckets-request]]
+[id="{upid}-{api}-request"]
 ==== Get Overall Buckets Request
 
-A `GetOverallBucketsRequest` object gets created with one or more `jobId`.
+A +{request}+ object gets created with one or more `jobId`.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-overall-buckets-request]
+include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
 <1> Constructing a new request referencing job IDs `jobId1` and `jobId2`.
 
@@ -22,86 +27,51 @@ The following arguments are optional:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-overall-buckets-bucket-span]
+include-tagged::{doc-tests-file}[{api}-bucket-span]
 --------------------------------------------------
 <1> The span of the overall buckets. Must be greater or equal to the jobs' largest `bucket_span`.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-overall-buckets-end]
+include-tagged::{doc-tests-file}[{api}-end]
 --------------------------------------------------
 <1> Overall buckets with timestamps earlier than this time will be returned.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-overall-buckets-exclude-interim]
+include-tagged::{doc-tests-file}[{api}-exclude-interim]
 --------------------------------------------------
 <1> If `true`, interim results will be excluded. Overall buckets are interim if any of the job buckets
 within the overall bucket interval are interim. Defaults to `false`.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-overall-buckets-overall-score]
+include-tagged::{doc-tests-file}[{api}-overall-score]
 --------------------------------------------------
 <1> Overall buckets with overall scores greater or equal than this value will be returned.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-overall-buckets-start]
+include-tagged::{doc-tests-file}[{api}-start]
 --------------------------------------------------
 <1> Overall buckets with timestamps on or after this time will be returned.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-overall-buckets-top-n]
+include-tagged::{doc-tests-file}[{api}-top-n]
 --------------------------------------------------
 <1> The number of top job bucket scores to be used in the `overall_score` calculation. Defaults to `1`.
 
-[[java-rest-high-x-pack-ml-get-overall-buckets-execution]]
-==== Execution
+include::../execution.asciidoc[]
 
-The request can be executed through the `MachineLearningClient` contained
-in the `RestHighLevelClient` object, accessed via the `machineLearningClient()` method.
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-overall-buckets-execute]
---------------------------------------------------
-
-[[java-rest-high-x-pack-ml-get-overall-buckets-execution-async]]
-==== Asynchronous Execution
-
-The request can also be executed asynchronously:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-overall-buckets-execute-async]
---------------------------------------------------
-<1> The `GetOverallBucketsRequest` to execute and the `ActionListener` to use when
-the execution completes
-
-The asynchronous method does not block and returns immediately. Once it is
-completed the `ActionListener` is called back with the `onResponse` method
-if the execution is successful or the `onFailure` method if the execution
-failed.
-
-A typical listener for `GetBucketsResponse` looks like:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-overall-buckets-listener]
---------------------------------------------------
-<1> `onResponse` is called back when the action is completed successfully
-<2> `onFailure` is called back when some unexpected error occurs
-
-[[java-rest-high-x-pack-ml-get-overall-buckets-response]]
+[id="{upid}-{api}-response"]
 ==== Get Overall Buckets Response
 
-The returned `GetOverallBucketsResponse` contains the requested buckets:
+The returned +{response}+ contains the requested buckets:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-overall-buckets-response]
+include-tagged::{doc-tests-file}[{api}-response]
 --------------------------------------------------
 <1> The count of overall buckets that were matched
 <2> The overall buckets retrieved

docs/java-rest/high-level/ml/get-records.asciidoc

@@ -1,18 +1,23 @@
-[[java-rest-high-x-pack-ml-get-records]]
+--
+:api: get-records 
+:request: GetRecordsRequest
+:response: GetRecordsResponse
+--
+[id="{upid}-{api}"]
 === Get Records API
 
 The Get Records API retrieves one or more record results.
-It accepts a `GetRecordsRequest` object and responds
-with a `GetRecordsResponse` object.
+It accepts a +{request}+ object and responds
+with a +{response}+ object.
 
-[[java-rest-high-x-pack-ml-get-records-request]]
+[id="{upid}-{api}-request"]
 ==== Get Records Request
 
-A `GetRecordsRequest` object gets created with an existing non-null `jobId`.
+A +{request}+ object gets created with an existing non-null `jobId`.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-records-request]
+include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
 <1> Constructing a new request referencing an existing `jobId`
 
@@ -21,93 +26,57 @@ The following arguments are optional:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-records-desc]
+include-tagged::{doc-tests-file}[{api}-desc]
 --------------------------------------------------
 <1> If `true`, the records are sorted in descending order. Defaults to `false`.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-records-end]
+include-tagged::{doc-tests-file}[{api}-end]
 --------------------------------------------------
 <1> Records with timestamps earlier than this time will be returned.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-records-exclude-interim]
+include-tagged::{doc-tests-file}[{api}-exclude-interim]
 --------------------------------------------------
 <1> If `true`, interim results will be excluded. Defaults to `false`.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-records-page]
+include-tagged::{doc-tests-file}[{api}-page]
 --------------------------------------------------
 <1> The page parameters `from` and `size`. `from` specifies the number of records to skip.
 `size` specifies the maximum number of records to get. Defaults to `0` and `100` respectively.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-records-record-score]
+include-tagged::{doc-tests-file}[{api}-record-score]
 --------------------------------------------------
 <1> Records with record_score greater or equal than this value will be returned.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-records-sort]
+include-tagged::{doc-tests-file}[{api}-sort]
 --------------------------------------------------
 <1> The field to sort records on. Defaults to `record_score`.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-records-start]
+include-tagged::{doc-tests-file}[{api}-start]
 --------------------------------------------------
 <1> Records with timestamps on or after this time will be returned.
 
-[[java-rest-high-x-pack-ml-get-records-execution]]
-==== Execution
+include::../execution.asciidoc[]
 
-The request can be executed through the `MachineLearningClient` contained
-in the `RestHighLevelClient` object, accessed via the `machineLearningClient()` method.
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-records-execute]
---------------------------------------------------
-
-
-[[java-rest-high-x-pack-ml-get-records-execution-async]]
-==== Asynchronous Execution
-
-The request can also be executed asynchronously:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-records-execute-async]
---------------------------------------------------
-<1> The `GetRecordsRequest` to execute and the `ActionListener` to use when
-the execution completes
-
-The asynchronous method does not block and returns immediately. Once it is
-completed the `ActionListener` is called back with the `onResponse` method
-if the execution is successful or the `onFailure` method if the execution
-failed.
-
-A typical listener for `GetRecordsResponse` looks like:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-records-listener]
---------------------------------------------------
-<1> `onResponse` is called back when the action is completed successfully
-<2> `onFailure` is called back when some unexpected error occurs
-
-[[java-rest-high-x-pack-ml-get-records-response]]
+[id="{upid}-{api}-response"]
 ==== Get Records Response
 
-The returned `GetRecordsResponse` contains the requested records:
+The returned +{response}+ contains the requested records:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-records-response]
+include-tagged::{doc-tests-file}[{api}-response]
 --------------------------------------------------
 <1> The count of records that were matched
 <2> The records retrieved

docs/java-rest/high-level/ml/open-job.asciidoc

@@ -1,55 +1,36 @@
-[[java-rest-high-x-pack-ml-open-job]]
+--
+:api: open-job
+:request: OpenJobRequest
+:response: OpenJobResponse
+--
+[id="{upid}-{api}"]
 === Open Job API
 
 The Open Job API provides the ability to open {ml} jobs in the cluster.
-It accepts a `OpenJobRequest` object and responds
-with a `OpenJobResponse` object.
+It accepts a +{request}+ object and responds
+with a +{response}+ object.
 
-[[java-rest-high-x-pack-ml-open-job-request]]
+[id="{upid}-{api}-request"]
 ==== Open Job Request
 
-An `OpenJobRequest` object gets created with an existing non-null `jobId`.
+An +{request}+ object gets created with an existing non-null `jobId`.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-open-job-request]
+include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
 <1> Constructing a new request referencing an existing `jobId`
 <2> Optionally setting the `timeout` value for how long the
 execution should wait for the job to be opened.
 
-[[java-rest-high-x-pack-ml-open-job-execution]]
-==== Execution
-
-The request can be executed through the `MachineLearningClient` contained
-in the `RestHighLevelClient` object, accessed via the `machineLearningClient()` method.
+[id="{upid}-{api}-response"]
+==== Open Job Response
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-open-job-execute]
+include-tagged::{doc-tests-file}[{api}-response]
 --------------------------------------------------
-<1> `isOpened()` from the `OpenJobResponse` indicates if the job was successfully
+<1> `isOpened()` from the +{response}+ indicates if the job was successfully
 opened or not.
 
-[[java-rest-high-x-pack-ml-open-job-execution-async]]
-==== Asynchronous Execution
-
-The request can also be executed asynchronously:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-open-job-execute-async]
---------------------------------------------------
-<1> The `OpenJobRequest` to execute and the `ActionListener` to use when
-the execution completes
-
-The method does not block and returns immediately. The passed `ActionListener` is used
-to notify the caller of completion. A typical `ActionListener` for `OpenJobResponse` may
-look like
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-open-job-listener]
---------------------------------------------------
-<1> `onResponse` is called back when the action is completed successfully
-<2> `onFailure` is called back when some unexpected error occurs
+include::../execution.asciidoc[]

docs/java-rest/high-level/ml/post-data.asciidoc

@@ -1,27 +1,32 @@
-[[java-rest-high-x-pack-ml-post-data]]
+--
+:api: post-data
+:request: PostDataRequest
+:response: PostDataResponse
+--
+[id="{upid}-{api}"]
 === Post Data API
 
 The Post Data API provides the ability to post data to an open
  {ml} job in the cluster.
-It accepts a `PostDataRequest` object and responds
-with a `PostDataResponse` object.
+It accepts a +{request}+ object and responds
+with a +{response}+ object.
 
-[[java-rest-high-x-pack-ml-post-data-request]]
+[id="{upid}-{api}-request"]
 ==== Post Data Request
 
-A `PostDataRequest` object gets created with an existing non-null `jobId`
+A +{request}+ object gets created with an existing non-null `jobId`
 and the `XContentType` being sent. Individual docs can be added
 incrementally via the `PostDataRequest.JsonBuilder#addDoc` method.
-These are then serialized and sent in bulk when passed to the `PostDataRequest`.
+These are then serialized and sent in bulk when passed to the +{request}+.
 
 Alternatively, the serialized bulk content can be set manually, along with its `XContentType`
-through one of the other `PostDataRequest` constructors.
+through one of the other +{request}+ constructors.
 
 Only `XContentType.JSON` and `XContentType.SMILE` are supported.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-post-data-request]
+include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
 <1> Create a new `PostDataRequest.JsonBuilder` object for incrementally adding documents
 <2> Add a new document as a `Map<String, Object>` object
@@ -34,53 +39,21 @@ The following arguments are optional.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-post-data-request-options]
+include-tagged::{doc-tests-file}[{api}-request-options]
 --------------------------------------------------
 <1> Set the start of the bucket resetting time
 <2> Set the end of the bucket resetting time
 
-[[java-rest-high-x-pack-ml-post-data-execution]]
-==== Execution
+include::../execution.asciidoc[]
 
-The request can be executed through the `MachineLearningClient` contained
-in the `RestHighLevelClient` object, accessed via the `machineLearningClient()` method.
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-post-data-execute]
---------------------------------------------------
-
-[[java-rest-high-x-pack-ml-post-data-execution-async]]
-==== Asynchronous Execution
-
-The request can also be executed asynchronously:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-post-data-execute-async]
---------------------------------------------------
-<1> The `PostDataRequest` to execute and the `ActionListener` to use when
-the execution completes
-
-The method does not block and returns immediately. The passed `ActionListener` is used
-to notify the caller of completion. A typical `ActionListener` for `PostDataResponse` may
-look like
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-post-data-listener]
---------------------------------------------------
-<1> `onResponse` is called back when the action is completed successfully
-<2> `onFailure` is called back when some unexpected error occurs
-
-[[java-rest-high-x-pack-ml-post-data-response]]
+[id="{upid}-{api}-response"]
 ==== Post Data Response
 
-A `PostDataResponse` contains current data processing statistics.
+A +{response}+ contains current data processing statistics.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-post-data-response]
+include-tagged::{doc-tests-file}[{api}-response]
 --------------------------------------------------
 <1> `getDataCounts()` a `DataCounts` object containing the current
 data processing counts.

docs/java-rest/high-level/ml/put-calendar.asciidoc

@@ -1,65 +1,35 @@
-[[java-rest-high-x-pack-ml-put-calendar]]
+--
+:api: put-calendar
+:request: PutCalendarRequest
+:response: PutCalendarResponse
+--
+[id="{upid}-{api}"]
 === Put Calendar API
 Creates a new {ml} calendar.
-The API accepts a `PutCalendarRequest` and responds
-with a `PutCalendarResponse` object.
+The API accepts a +{request}+ and responds
+with a +{response}+ object.
 
-[[java-rest-high-x-pack-ml-put-calendar-request]]
+[id="{upid}-{api}-request"]
 ==== Put Calendar Request
 
-A `PutCalendarRequest` is constructed with a Calendar object
+A +{request}+ is constructed with a Calendar object
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-put-calendar-request]
+include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
 <1> Create a request with the given Calendar
 
 
-[[java-rest-high-x-pack-ml-put-calendar-response]]
+[id="{upid}-{api}-response"]
 ==== Put Calendar Response
 
-The returned `PutCalendarResponse` contains the created Calendar:
+The returned +{response}+ contains the created Calendar:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-put-calendar-response]
+include-tagged::{doc-tests-file}[{api}-response]
 --------------------------------------------------
 <1> The created Calendar
 
-[[java-rest-high-x-pack-ml-put-calendar-execution]]
-==== Execution
-The request can be executed through the `MachineLearningClient` contained
-in the `RestHighLevelClient` object, accessed via the `machineLearningClient()` method.
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-put-calendar-execute]
---------------------------------------------------
-
-[[java-rest-high-x-pack-ml-put-calendar-execution-async]]
-==== Asynchronous Execution
-
-The request can also be executed asynchronously:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-put-calendar-execute-async]
---------------------------------------------------
-<1> The `PutCalendarResquest` to execute and the `ActionListener` to use when
-the execution completes
-
-The asynchronous method does not block and returns immediately. Once it is
-completed the `ActionListener` is called back with the `onResponse` method
-if the execution is successful or the `onFailure` method if the execution
-failed.
-
-A typical listener for `PutCalendarResponse` looks like:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-put-calendar-listener]
---------------------------------------------------
-<1> `onResponse` is called back when the action is completed successfully
-<2> `onFailure` is called back when some unexpected error occurs
-
+include::../execution.asciidoc[]

docs/java-rest/high-level/ml/put-datafeed.asciidoc

@@ -1,22 +1,27 @@
-[[java-rest-high-x-pack-ml-put-datafeed]]
+--
+:api: put-datafeed
+:request: PutDatafeedRequest
+:response: PutDatafeedResponse
+--
+[id="{upid}-{api}"]
 === Put Datafeed API
 
 The Put Datafeed API can be used to create a new {ml} datafeed
-in the cluster. The API accepts a `PutDatafeedRequest` object
-as a request and returns a `PutDatafeedResponse`.
+in the cluster. The API accepts a +{request}+ object
+as a request and returns a +{response}+.
 
-[[java-rest-high-x-pack-ml-put-datafeed-request]]
+[id="{upid}-{api}-request"]
 ==== Put Datafeed Request
 
-A `PutDatafeedRequest` requires the following argument:
+A +{request}+ requires the following argument:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-put-datafeed-request]
+include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
 <1> The configuration of the {ml} datafeed to create
 
-[[java-rest-high-x-pack-ml-put-datafeed-config]]
+[id="{upid}-{api}-config"]
 ==== Datafeed Configuration
 
 The `DatafeedConfig` object contains all the details about the {ml} datafeed
@@ -26,7 +31,7 @@ A `DatafeedConfig` requires the following arguments:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-create-datafeed-config]
+include-tagged::{doc-tests-file}[{api}-config]
 --------------------------------------------------
 <1> The datafeed ID and the job ID
 <2> The indices that contain the data to retrieve and feed into the job
@@ -36,89 +41,52 @@ The following arguments are optional:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-create-datafeed-config-set-chunking-config]
+include-tagged::{doc-tests-file}[{api}-config-set-chunking-config]
 --------------------------------------------------
 <1> Specifies how data searches are split into time chunks.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-create-datafeed-config-set-frequency]
+include-tagged::{doc-tests-file}[{api}-config-set-frequency]
 --------------------------------------------------
 <1> The interval at which scheduled queries are made while the datafeed runs in real time.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-create-datafeed-config-set-query]
+include-tagged::{doc-tests-file}[{api}-config-set-query]
 --------------------------------------------------
 <1> A query to filter the search results by. Defaults to the `match_all` query.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-create-datafeed-config-set-query-delay]
+include-tagged::{doc-tests-file}[{api}-config-set-query-delay]
 --------------------------------------------------
 <1> The time interval behind real time that data is queried.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-create-datafeed-config-set-script-fields]
+include-tagged::{doc-tests-file}[{api}-config-set-script-fields]
 --------------------------------------------------
 <1> Allows the use of script fields.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-create-datafeed-config-set-scroll-size]
+include-tagged::{doc-tests-file}[{api}-config-set-scroll-size]
 --------------------------------------------------
 <1> The `size` parameter used in the searches.
 
-[[java-rest-high-x-pack-ml-put-datafeed-execution]]
-==== Execution
+include::../execution.asciidoc[]
 
-The Put Datafeed API can be executed through a `MachineLearningClient`
-instance. Such an instance can be retrieved from a `RestHighLevelClient`
-using the `machineLearning()` method:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-put-datafeed-execute]
---------------------------------------------------
-
-[[java-rest-high-x-pack-ml-put-datafeed-response]]
+[id="{upid}-{api}-response"]
 ==== Response
 
-The returned `PutDatafeedResponse` returns the full representation of
+The returned +{response}+ returns the full representation of
 the new {ml} datafeed if it has been successfully created. This will
 contain the creation time and other fields initialized using
 default values:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-put-datafeed-response]
+include-tagged::{doc-tests-file}[{api}-response]
 --------------------------------------------------
 <1> The created datafeed
-
-[[java-rest-high-x-pack-ml-put-datafeed-async]]
-==== Asynchronous Execution
-
-This request can be executed asynchronously:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-put-datafeed-execute-async]
---------------------------------------------------
-<1> The `PutDatafeedRequest` to execute and the `ActionListener` to use when
-the execution completes
-
-The asynchronous method does not block and returns immediately. Once it is
-completed the `ActionListener` is called back using the `onResponse` method
-if the execution successfully completed or using the `onFailure` method if
-it failed.
-
-A typical listener for `PutDatafeedResponse` looks like:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-put-datafeed-execute-listener]
---------------------------------------------------
-<1> Called when the execution is successfully completed. The response is
-provided as an argument
-<2> Called in case of failure. The raised exception is provided as an argument

docs/java-rest/high-level/ml/put-job.asciidoc

@@ -1,22 +1,27 @@
-[[java-rest-high-x-pack-ml-put-job]]
+--
+:api: put-job
+:request: PutJobRequest
+:response: PutJobResponse
+--
+[id="{upid}-{api}"]
 === Put Job API
 
 The Put Job API can be used to create a new {ml} job
-in the cluster. The API accepts a `PutJobRequest` object
-as a request and returns a `PutJobResponse`.
+in the cluster. The API accepts a +{request}+ object
+as a request and returns a +{response}+.
 
-[[java-rest-high-x-pack-ml-put-job-request]]
+[id="{upid}-{api}-request"]
 ==== Put Job Request
 
-A `PutJobRequest` requires the following argument:
+A +{request}+ requires the following argument:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-put-job-request]
+include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
 <1> The configuration of the {ml} job to create as a `Job`
 
-[[java-rest-high-x-pack-ml-put-job-config]]
+[id="{upid}-{api}-config"]
 ==== Job Configuration
 
 The `Job` object contains all the details about the {ml} job
@@ -26,14 +31,14 @@ A `Job` requires the following arguments:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-put-job-config]
+include-tagged::{doc-tests-file}[{api}-config]
 --------------------------------------------------
 <1> The job ID
 <2> An analysis configuration
 <3> A data description
 <4> Optionally, a human-readable description
 
-[[java-rest-high-x-pack-ml-put-job-analysis-config]]
+[id="{upid}-{api}-analysis-config"]
 ==== Analysis Configuration
 
 The analysis configuration of the {ml} job is defined in the `AnalysisConfig`.
@@ -64,7 +69,7 @@ An example of building a `Detector` instance is as follows:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-put-job-detector]
+include-tagged::{doc-tests-file}[{api}-detector]
 --------------------------------------------------
 <1> The function to use
 <2> The field to apply the function to
@@ -74,13 +79,13 @@ Then the same configuration would be:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-put-job-analysis-config]
+include-tagged::{doc-tests-file}[{api}-analysis-config]
 --------------------------------------------------
 <1> Create a list of detectors
 <2> Pass the list of detectors to the analysis config builder constructor
 <3> The bucket span
 
-[[java-rest-high-x-pack-ml-put-job-data-description]]
+[id="{upid}-{api}-data-description"]
 ==== Data Description
 
 After defining the analysis config, the next thing to define is the
@@ -103,59 +108,22 @@ configuration would be:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-put-job-data-description]
+include-tagged::{doc-tests-file}[{api}-data-description]
 --------------------------------------------------
 <1> The time field
 
-[[java-rest-high-x-pack-ml-put-job-execution]]
-==== Execution
+include::../execution.asciidoc[]
 
-The Put Job API can be executed through a `MachineLearningClient`
-instance. Such an instance can be retrieved from a `RestHighLevelClient`
-using the `machineLearning()` method:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-put-job-execute]
---------------------------------------------------
-
-[[java-rest-high-x-pack-ml-put-job-response]]
+[id="{upid}-{api}-response"]
 ==== Response
 
-The returned `PutJobResponse` returns the full representation of
+The returned +{response}+ returns the full representation of
 the new {ml} job if it has been successfully created. This will
 contain the creation time and other fields initialized using
 default values:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-put-job-response]
+include-tagged::{doc-tests-file}[{api}-response]
 --------------------------------------------------
 <1> The creation time is a field that was not passed in the `Job` object in the request
-
-[[java-rest-high-x-pack-ml-put-job-async]]
-==== Asynchronous Execution
-
-This request can be executed asynchronously:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-put-job-execute-async]
---------------------------------------------------
-<1> The `PutJobRequest` to execute and the `ActionListener` to use when
-the execution completes
-
-The asynchronous method does not block and returns immediately. Once it is
-completed the `ActionListener` is called back using the `onResponse` method
-if the execution successfully completed or using the `onFailure` method if
-it failed.
-
-A typical listener for `PutJobResponse` looks like:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-put-job-execute-listener]
---------------------------------------------------
-<1> Called when the execution is successfully completed. The response is
-provided as an argument
-<2> Called in case of failure. The raised exception is provided as an argument

docs/java-rest/high-level/ml/start-datafeed.asciidoc

@@ -1,19 +1,24 @@
-[[java-rest-high-x-pack-ml-start-datafeed]]
+--
+:api: start-datafeed
+:request: StartDatafeedRequest
+:response: StartDatafeedResponse
+--
+[id="{upid}-{api}"]
 === Start Datafeed API
 
 The Start Datafeed API provides the ability to start a {ml} datafeed in the cluster.
-It accepts a `StartDatafeedRequest` object and responds
-with a `StartDatafeedResponse` object.
+It accepts a +{request}+ object and responds
+with a +{response}+ object.
 
-[[java-rest-high-x-pack-ml-start-datafeed-request]]
+[id="{upid}-{api}-request"]
 ==== Start Datafeed Request
 
-A `StartDatafeedRequest` object is created referencing a non-null `datafeedId`.
+A +{request}+ object is created referencing a non-null `datafeedId`.
 All other fields are optional for the request.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-start-datafeed-request]
+include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
 <1> Constructing a new request referencing an existing `datafeedId`
 
@@ -23,7 +28,7 @@ The following arguments are optional.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-start-datafeed-request-options]
+include-tagged::{doc-tests-file}[{api}-request-options]
 --------------------------------------------------
 <1> Set when the datafeed should end, the value is exclusive.
 May be an epoch seconds, epoch millis or an ISO 8601 string.
@@ -35,37 +40,4 @@ If you do not specify a start time and the datafeed is associated with a new job
 the analysis starts from the earliest time for which data is available.
 <3> Set the timeout for the request
 
-[[java-rest-high-x-pack-ml-start-datafeed-execution]]
-==== Execution
-
-The request can be executed through the `MachineLearningClient` contained
-in the `RestHighLevelClient` object, accessed via the `machineLearningClient()` method.
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-start-datafeed-execute]
---------------------------------------------------
-<1> Did the datafeed successfully start?
-
-[[java-rest-high-x-pack-ml-start-datafeed-execution-async]]
-==== Asynchronous Execution
-
-The request can also be executed asynchronously:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-start-datafeed-execute-async]
---------------------------------------------------
-<1> The `StartDatafeedRequest` to execute and the `ActionListener` to use when
-the execution completes
-
-The method does not block and returns immediately. The passed `ActionListener` is used
-to notify the caller of completion. A typical `ActionListener` for `StartDatafeedResponse` may
-look like
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-start-datafeed-listener]
---------------------------------------------------
-<1> `onResponse` is called back when the action is completed successfully
-<2> `onFailure` is called back when some unexpected error occurs
+include::../execution.asciidoc[]

docs/java-rest/high-level/ml/stop-datafeed.asciidoc

@@ -1,20 +1,25 @@
-[[java-rest-high-x-pack-ml-stop-datafeed]]
+--
+:api: stop-datafeed
+:request: StopDatafeedRequest
+:response: StopDatafeedResponse
+--
+[id="{upid}-{api}"]
 === Stop Datafeed API
 
 The Stop Datafeed API provides the ability to stop a {ml} datafeed in the cluster.
-It accepts a `StopDatafeedRequest` object and responds
-with a `StopDatafeedResponse` object.
+It accepts a +{request}+ object and responds
+with a +{response}+ object.
 
-[[java-rest-high-x-pack-ml-stop-datafeed-request]]
+[id="{upid}-{api}-request"]
 ==== Stop Datafeed Request
 
-A `StopDatafeedRequest` object is created referencing any number of non-null `datafeedId` entries.
+A +{request}+ object is created referencing any number of non-null `datafeedId` entries.
 Wildcards and `_all` are also accepted.
 All other fields are optional for the request.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-stop-datafeed-request]
+include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
 <1> Constructing a new request referencing existing `datafeedId` entries.
 
@@ -24,43 +29,10 @@ The following arguments are optional.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-stop-datafeed-request-options]
+include-tagged::{doc-tests-file}[{api}-request-options]
 --------------------------------------------------
 <1> Whether to ignore if a wildcard expression matches no datafeeds. (This includes `_all` string)
 <2> If true, the datafeed is stopped forcefully.
 <3> Controls the amount of time to wait until a datafeed stops. The default value is 20 seconds.
 
-[[java-rest-high-x-pack-ml-stop-datafeed-execution]]
-==== Execution
-
-The request can be executed through the `MachineLearningClient` contained
-in the `RestHighLevelClient` object, accessed via the `machineLearningClient()` method.
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-stop-datafeed-execute]
---------------------------------------------------
-<1> Did the datafeed successfully stop?
-
-[[java-rest-high-x-pack-ml-stop-datafeed-execution-async]]
-==== Asynchronous Execution
-
-The request can also be executed asynchronously:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-stop-datafeed-execute-async]
---------------------------------------------------
-<1> The `StopDatafeedRequest` to execute and the `ActionListener` to use when
-the execution completes
-
-The method does not block and returns immediately. The passed `ActionListener` is used
-to notify the caller of completion. A typical `ActionListener` for `StopDatafeedResponse` may
-look like
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-stop-datafeed-listener]
---------------------------------------------------
-<1> `onResponse` is called back when the action is completed successfully
-<2> `onFailure` is called back when some unexpected error occurs
+include::../execution.asciidoc[]

docs/java-rest/high-level/ml/update-job.asciidoc

@@ -1,18 +1,23 @@
-[[java-rest-high-x-pack-ml-update-job]]
+--
+:api: update-job
+:request: UpdateJobRequest
+:response: PutJobResponse
+--
+[id="{upid}-{api}"]
 === Update Job API
 
 The Update Job API provides the ability to update a {ml} job.
-It accepts a `UpdateJobRequest` object and responds
-with a `PutJobResponse` object.
+It accepts a +{request}+ object and responds
+with a +{response}+ object.
 
-[[java-rest-high-x-pack-ml-update-job-request]]
+[id="{upid}-{api}-request"]
 ==== Update Job Request
 
-An `UpdateJobRequest` object gets created with a `JobUpdate` object.
+An +{request}+ object gets created with a `JobUpdate` object.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-update-job-request]
+include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
 <1> Constructing a new request referencing a `JobUpdate` object
 
@@ -23,7 +28,7 @@ job. An existing, non-null `jobId` must be referenced in its creation.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-update-job-options]
+include-tagged::{doc-tests-file}[{api}-options]
 --------------------------------------------------
 <1> Mandatory, non-null `jobId` referencing an existing {ml} job
 <2> Updated description
@@ -41,53 +46,21 @@ include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-update-job-op
 Included with these options are specific optional `JobUpdate.DetectorUpdate` updates.
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-update-job-detector-options]
+include-tagged::{doc-tests-file}[{api}-detector-options]
 --------------------------------------------------
 <1> The index of the detector. `O` means unknown
 <2> The optional description of the detector
 <3> The `DetectionRule` rules that apply to this detector
 
-[[java-rest-high-x-pack-ml-update-job-execution]]
-==== Execution
+include::../execution.asciidoc[]
 
-The request can be executed through the `MachineLearningClient` contained
-in the `RestHighLevelClient` object, accessed via the `machineLearningClient()` method.
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-update-job-execute]
---------------------------------------------------
-
-[[java-rest-high-x-pack-ml-update-job-execution-async]]
-==== Asynchronous Execution
-
-The request can also be executed asynchronously:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-update-job-execute-async]
---------------------------------------------------
-<1> The `UpdateJobRequest` to execute and the `ActionListener` to use when
-the execution completes
-
-The method does not block and returns immediately. The passed `ActionListener` is used
-to notify the caller of completion. A typical `ActionListener` for `PutJobResponse` may
-look like
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-update-job-listener]
---------------------------------------------------
-<1> `onResponse` is called back when the action is completed successfully
-<2> `onFailure` is called back when some unexpected error occurs
-
-[[java-rest-high-x-pack-ml-update-job-response]]
+[id="{upid}-{api}-response"]
 ==== Update Job Response
 
-A `PutJobResponse` contains the updated `Job` object
+A +{response}+ contains the updated `Job` object
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-update-job-response]
+include-tagged::{doc-tests-file}[{api}-response]
 --------------------------------------------------
 <1> `getResponse()` returns the updated `Job` object