[DOCS] Reformat rollup API docs (#49397)

Author: lcawl

docs/reference/rollup/apis/get-job.asciidoc

@@ -18,9 +18,9 @@ experimental[]
 [[rollup-get-job-prereqs]]
 ==== {api-prereq-title}
 
-* You must have `monitor`, `monitor_rollup`, `manage` or `manage_rollup` cluster
-privileges to use this API. For more information, see
-<<security-privileges>>.
+* If the {es} {security-features} are enabled, you must have `monitor`,
+`monitor_rollup`, `manage` or `manage_rollup` cluster privileges to use this API.
+For more information, see <<security-privileges>>.
 
 [[rollup-get-job-desc]]
 ==== {api-description-title}

docs/reference/rollup/apis/put-job.asciidoc

@@ -32,7 +32,7 @@ Jobs are created in a `STOPPED` state. You can start them with the
 [[rollup-put-job-api-path-params]]
 ==== {api-path-parms-title}
 
-`job_id`::
+`<job_id>`::
   (Required, string) Identifier for the {rollup-job}.
 
 [[rollup-put-job-api-request-body]]

docs/reference/rollup/apis/rollup-caps.asciidoc

@@ -1,17 +1,32 @@
 [role="xpack"]
 [testenv="basic"]
 [[rollup-get-rollup-caps]]
-=== Get rollup job capabilities API
+=== Get {rollup-job} capabilities API
 ++++
 <titleabbrev>Get rollup caps</titleabbrev>
 ++++
 
+Returns the capabilities of any {rollup-jobs} that have been configured for a
+specific index or index pattern.
+
 experimental[]
 
-This API returns the capabilities of any rollup jobs that have been configured
-for a specific index or index pattern.
+[[rollup-get-rollup-caps-request]]
+==== {api-request-title}
+
+`GET _rollup/data/<index>`
+
+[[rollup-get-rollup-caps-prereqs]]
+==== {api-prereq-title}
 
-This API is useful because a rollup job is often configured to rollup only a
+* If the {es} {security-features} are enabled, you must have `monitor`,
+`monitor_rollup`, `manage` or `manage_rollup` cluster privileges to use this API.
+For more information, see <<security-privileges>>.
+
+[[rollup-get-rollup-caps-desc]]
+==== {api-description-title}
+
+This API is useful because a {rollup-job} is often configured to rollup only a
 subset of fields from the source index. Furthermore, only certain aggregations
 can be configured for various fields, leading to a limited subset of
 functionality depending on that configuration.
@@ -22,33 +37,20 @@ This API enables you to inspect an index and determine:
 2. If yes to the first question, what fields were rolled up, what aggregations
 can be performed, and where does the data live?
 
-==== Request
-
-`GET _rollup/data/{index}`
-
-//===== Description
-
-==== Path Parameters
-
-`index`::
-  (string) Index, indices or index-pattern to return rollup capabilities for.  `_all` may be used to fetch
-  rollup capabilities from all jobs
-
-
-==== Request Body
-
-There is no request body for the Get Rollup Caps API.
+[[rollup-get-rollup-path-params]]
+==== {api-path-parms-title}
 
-==== Authorization
+`<index>`::
+  (string) Index, indices or index-pattern to return rollup capabilities for. 
+  `_all` may be used to fetch rollup capabilities from all jobs.
 
-You must have `monitor`, `monitor_rollup`, `manage` or `manage_rollup` cluster privileges to use this API.
-For more information, see
-<<security-privileges>>.
 
-==== Examples
+[[rollup-get-rollup-example]]
+==== {api-examples-title}
 
-Imagine we have an index named `sensor-1` full of raw data.  We know that the data will grow over time, so there
-will be a `sensor-2`, `sensor-3`, etc.  Let's create a Rollup job that targets the index pattern `sensor-*` to accommodate
+Imagine we have an index named `sensor-1` full of raw data.  We know that the
+data will grow over time, so there will be a `sensor-2`, `sensor-3`, etc.  Let's
+create a {rollup-job} that targets the index pattern `sensor-*` to accommodate
 this future scaling:
 
 [source,console]
@@ -83,7 +85,8 @@ PUT _rollup/job/sensor
 --------------------------------------------------
 // TEST[setup:sensor_index]
 
-We can then retrieve the rollup capabilities of that index pattern (`sensor-*`) via the following command:
+We can then retrieve the rollup capabilities of that index pattern (`sensor-*`)
+via the following command:
 
 [source,console]
 --------------------------------------------------
@@ -139,17 +142,21 @@ Which will yield the following response:
 }
 ----
 
-The response that is returned contains information that is similar to the original Rollup configuration, but formatted
-differently.  First, there are some house-keeping details: the Rollup job's ID, the index that holds the rolled data,
-the index pattern that the job was targeting.
+The response that is returned contains information that is similar to the
+original rollup configuration, but formatted differently.  First, there are some
+house-keeping details: the {rollup-job} ID, the index that holds the rolled data,
+and the index pattern that the job was targeting.
 
-Next it shows a list of fields that contain data eligible for rollup searches.  Here we see four fields: `node`, `temperature`,
-`timestamp` and `voltage`.  Each of these fields list the aggregations that are possible.  For example, you can use a min, max
-or sum aggregation on the `temperature` field, but only a `date_histogram` on `timestamp`.
+Next it shows a list of fields that contain data eligible for rollup searches.
+Here we see four fields: `node`, `temperature`, `timestamp` and `voltage`. Each
+of these fields list the aggregations that are possible. For example, you can
+use a min, max or sum aggregation on the `temperature` field, but only a
+`date_histogram` on `timestamp`.
 
-Note that the `rollup_jobs` element is an array; there can be multiple, independent jobs configured for a single index
-or index pattern.  Each of these jobs may have different configurations, so the API returns a list of all the various
-configurations available.
+Note that the `rollup_jobs` element is an array; there can be multiple,
+independent jobs configured for a single index or index pattern. Each of these
+jobs may have different configurations, so the API returns a list of all the
+various configurations available.
 
 We could also retrieve the same information with a request to `_all`:
 
@@ -159,7 +166,8 @@ GET _rollup/data/_all
 --------------------------------------------------
 // TEST[continued]
 
-But note that if we use the concrete index name (`sensor-1`), we'll retrieve no rollup capabilities:
+But note that if we use the concrete index name (`sensor-1`), we'll retrieve no
+rollup capabilities:
 
 [source,console]
 --------------------------------------------------
@@ -174,7 +182,9 @@ GET _rollup/data/sensor-1
 }
 ----
 
-Why is this?  The original rollup job was configured against a specific index pattern (`sensor-*`) not a concrete index
-(`sensor-1`).  So while the index belongs to the pattern, the rollup job is only valid across the entirety of the pattern
-not just one of it's containing indices.  So for that reason, the Rollup Capabilities API only returns information based
-on the originally configured index name or pattern.
+Why is this?  The original {rollup-job} was configured against a specific index
+pattern (`sensor-*`) not a concrete index (`sensor-1`).  So while the index
+belongs to the pattern, the {rollup-job} is only valid across the entirety of
+the pattern not just one of it's containing indices. So for that reason, the
+get rollup capabilities API only returns information based on the originally
+configured index name or pattern.

docs/reference/rollup/apis/rollup-index-caps.asciidoc

@@ -6,41 +6,48 @@
 <titleabbrev>Get rollup index caps</titleabbrev>
 ++++
 
-experimental[]
-
-This API returns the rollup capabilities of all jobs inside of a rollup index (e.g. the index where rollup data is stored).
-A single rollup index may store the data for multiple rollup jobs, and may have a variety of capabilities depending on those jobs.
+Returns the rollup capabilities of all jobs inside of a rollup index (e.g. the
+index where rollup data is stored).
 
-This API will allow you to determine:
+experimental[]
 
-1. What jobs are stored in an index (or indices specified via a pattern)?
-2. What target indices were rolled up, what fields were used in those rollups and what aggregations can be performed on each job?
+[[rollup-get-rollup-index-caps-request]]
+==== {api-request-title}
 
-==== Request
+`GET <index>/_rollup/data`
 
-`GET {index}/_rollup/data`
+[[rollup-get-rollup-index-caps-prereqs]]
+==== {api-prereq-title}
 
-//===== Description
+* If the {es} {security-features} are enabled, you must have the `read` index
+privilege on the index that stores the rollup results. For more information, see
+<<security-privileges>>.
 
-==== Path Parameters
+[[rollup-get-rollup-index-caps-desc]]
+==== {api-description-title}
 
-`index`::
-  (string) Index or index-pattern of concrete rollup indices to check for capabilities.
+A single rollup index may store the data for multiple {rollup-jobs}, and may
+have a variety of capabilities depending on those jobs.
 
-==== Request Body
+This API will allow you to determine:
 
-There is no request body for the Get Jobs API.
+1. What jobs are stored in an index (or indices specified via a pattern)?
+2. What target indices were rolled up, what fields were used in those rollups
+and what aggregations can be performed on each job?
 
-==== Authorization
+[[rollup-get-rollup-index-caps-path-params]]
+==== {api-path-parms-title}
 
-You must have the `read` index privilege on the index that stores the rollup results.
-For more information, see
-<<security-privileges>>.
+`<index>`::
+  (Required, string) Index or index-pattern of concrete rollup indices to check
+  for capabilities.
 
-==== Examples
+[[rollup-get-rollup-index-caps-example]]
+==== {api-examples-title}
 
-Imagine we have an index named `sensor-1` full of raw data.  We know that the data will grow over time, so there
-will be a `sensor-2`, `sensor-3`, etc.  Let's create a Rollup job, which stores it's data in `sensor_rollup`:
+Imagine we have an index named `sensor-1` full of raw data.  We know that the
+data will grow over time, so there will be a `sensor-2`, `sensor-3`, etc. 
+Let's create a {rollup-job} that stores its data in `sensor_rollup`:
 
 [source,console]
 --------------------------------------------------
@@ -74,17 +81,17 @@ PUT _rollup/job/sensor
 --------------------------------------------------
 // TEST[setup:sensor_index]
 
-If at a later date, we'd like to determine what jobs and capabilities were stored in the `sensor_rollup` index, we can use the Get Rollup
-Index API:
+If at a later date, we'd like to determine what jobs and capabilities were
+stored in the `sensor_rollup` index, we can use the get rollup index API:
 
 [source,console]
 --------------------------------------------------
 GET /sensor_rollup/_rollup/data
 --------------------------------------------------
 // TEST[continued]
 
-Note how we are requesting the concrete rollup index name (`sensor_rollup`) as the first part of the URL.
-This  will yield the following response:
+Note how we are requesting the concrete rollup index name (`sensor_rollup`) as
+the first part of the URL. This  will yield the following response:
 
 [source,console-result]
 ----
@@ -133,20 +140,24 @@ This  will yield the following response:
 ----
 
 
-The response that is returned contains information that is similar to the original Rollup configuration, but formatted
-differently.  First, there are some house-keeping details: the Rollup job's ID, the index that holds the rolled data,
+The response that is returned contains information that is similar to the
+original rollup configuration, but formatted differently. First, there are some
+house-keeping details: the {rollup-job} ID, the index that holds the rolled data,
 the index pattern that the job was targeting.
 
-Next it shows a list of fields that contain data eligible for rollup searches.  Here we see four fields: `node`, `temperature`,
-`timestamp` and `voltage`.  Each of these fields list the aggregations that are possible.  For example, you can use a min, max
-or sum aggregation on the `temperature` field, but only a `date_histogram` on `timestamp`.
-
-Note that the `rollup_jobs` element is an array; there can be multiple, independent jobs configured for a single index
-or index pattern.  Each of these jobs may have different configurations, so the API returns a list of all the various
-configurations available.
+Next it shows a list of fields that contain data eligible for rollup searches. 
+Here we see four fields: `node`, `temperature`, `timestamp` and `voltage`. Each
+of these fields list the aggregations that are possible. For example, you can
+use a min, max, or sum aggregation on the `temperature` field, but only a
+`date_histogram` on `timestamp`.
 
+Note that the `rollup_jobs` element is an array; there can be multiple,
+independent jobs configured for a single index or index pattern. Each of these
+jobs may have different configurations, so the API returns a list of all the
+various configurations available.
 
-Like other APIs that interact with indices, you can specify index patterns instead of explicit indices:
+Like other APIs that interact with indices, you can specify index patterns
+instead of explicit indices:
 
 [source,console]
 --------------------------------------------------