[DOCS] Reformats cluster health and cluster state APIs

docs/reference/cluster/health.asciidoc

@@ -1,9 +1,141 @@
 [[cluster-health]]
 === Cluster Health
 
-The cluster health API allows to get a very simple status on the health
-of the cluster. For example, on a quiet single node cluster with a single index
-with one shard and one replica, this:
+Returns the health status of a cluster.
+
+[[cluster-health-api-request]]
+==== {api-request-title}
+
+`GET _cluster/health/{index}`
+
+[[cluster-health-api-desc]]
+==== {api-description-title}
+
+The cluster health API returns a simple status on the health of the 
+cluster. The API can also be executed against one or more indices to get just 
+the specified indices health.
+
+The cluster health status is: `green`, `yellow` or `red`. On the shard level, a 
+`red` status indicates that the specific shard is not allocated in the cluster, 
+`yellow` means that the primary shard is allocated but replicas are not, and 
+`green` means that all shards are allocated. The index level status is 
+controlled by the worst shard status. The cluster status is controlled by the 
+worst index status.
+
+One of the main benefits of the API is the ability to wait until the cluster 
+reaches a certain high water-mark health level. For example, the following will 
+wait for 50 seconds for the cluster to reach the `yellow` level (if it reaches 
+the `green` or `yellow` status before 50 seconds elapse, it will return at that 
+point):
+
+[source,js]
+--------------------------------------------------
+GET /_cluster/health?wait_for_status=yellow&timeout=50s
+--------------------------------------------------
+// CONSOLE
+
+[[cluster-health-api-path-params]]
+==== {api-path-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
+
+[[cluster-health-api-query-params]]
+==== {api-query-parms-title}
+
+`level`::
+    (Optional, string) Can be one of `cluster`, `indices` or `shards`. Controls 
+    the details level of the health information returned. Defaults to `cluster`.
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=local]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
+
+`wait_for_active_shards`::
+    (Optional, string) A number controlling to how many active shards to wait 
+    for, `all` to wait for all shards in the cluster to be active, or `0` to not 
+    wait. Defaults to `0`.
+
+`wait_for_events`::
+    (Optional, string) Can be one of `immediate`, `urgent`, `high`, `normal`, 
+    `low`, `languid`. Wait until all currently queued events with the given 
+    priority are processed.
+
+`wait_for_no_initializing_shards`::
+    (Optional, boolean) A boolean value which controls whether to wait (until 
+    the timeout provided) for the cluster to have no shard initializations. 
+    Defaults to false, which means it will not wait for initializing shards.
+
+`wait_for_no_relocating_shards`::
+    (Optional, boolean) A boolean value which controls whether to wait (until 
+    the timeout provided) for the cluster to have no shard relocations. Defaults 
+    to false, which means it will not wait for relocating shards.
+
+`wait_for_nodes`::
+    (Optional, string) The request waits until the specified number `N` of
+    nodes is available. It also accepts `>=N`, `<=N`, `>N` and `<N`.
+    Alternatively, it is possible to use `ge(N)`, `le(N)`, `gt(N)` and
+    `lt(N)` notation.
+
+`wait_for_status`::
+    (Optional, string) One of `green`, `yellow` or `red`. Will wait (until the 
+    timeout provided) until the status of the cluster changes to the one
+    provided or better, i.e. `green` > `yellow` > `red`. By default, will not
+    wait for any status.
+
+[[cluster-health-api-response-body]]
+==== {api-response-body-title}
+
+`cluster_name`::
+    (string) The name of the cluster.
+
+`status`::
+    (string) The health status of the cluster.
+
+`timed_out`::
+    (boolean) If `false` the response returned within the period of 
+    time that is specified by the `timeout` parameter (`30s` by default).
+
+`number_of_nodes`::
+    (integer) The number of nodes within the cluster.
+
+`number_of_data_nodes`::
+    (integer) The number of nodes that are dedicated data nodes.
+
+`active_primary_shards`::
+    (integer) The number of active primary shards.
+
+`active_shards`::
+    (integer) The total number of active primary and replica shards.
+
+`relocating_shards`::
+    (integer) The number of shards that are under relocation.
+
+`initializing_shards`::
+    (integer) The number of shards that are under initialization.
+
+`unassigned_shards`::
+    (integer) The number of shards that are not allocated.
+
+`delayed_unassigned_shards`::
+    (integer) The number of shards whose allocation has been delayed by the 
+    timeout settings.
+
+`number_of_pending_tasks`::
+    (integer) The number of cluster-level changes that have not yet been 
+    executed.
+
+`number_of_in_flight_fetch`::
+    (integer) The number of unfinished fetches.
+
+`task_max_waiting_in_queue_millis`::
+    (integer) The time expressed in milliseconds since the earliest initiated task 
+    is waiting for being performed.
+
+`active_shards_percent_as_number`::
+    (float) The ratio of active shards in the cluster expressed as a percentage. 
+
+[[cluster-health-api-example]]
+==== {api-examples-title}
 
 [source,js]
 --------------------------------------------------
@@ -12,7 +144,8 @@ GET _cluster/health
 // CONSOLE
 // TEST[s/^/PUT test1\n/]
 
-Returns this:
+The API returns the following response in case of a quiet single node cluster 
+with a single index with one shard and one replica:
 
 [source,js]
 --------------------------------------------------
@@ -38,90 +171,6 @@ Returns this:
 // TESTRESPONSE[s/"number_of_pending_tasks" : 0,/"number_of_pending_tasks" : $body.number_of_pending_tasks,/]
 // TESTRESPONSE[s/"task_max_waiting_in_queue_millis": 0/"task_max_waiting_in_queue_millis": $body.task_max_waiting_in_queue_millis/]
 
-
-The API can also be executed against one or more indices to get just the
-specified indices health:
-
-[source,js]
---------------------------------------------------
-GET /_cluster/health/test1,test2
---------------------------------------------------
-// CONSOLE
-// TEST[s/^/PUT test1\nPUT test2\n/]
-
-The cluster health status is: `green`, `yellow` or `red`. On the shard
-level, a `red` status indicates that the specific shard is not allocated
-in the cluster, `yellow` means that the primary shard is allocated but
-replicas are not, and `green` means that all shards are allocated. The
-index level status is controlled by the worst shard status. The cluster
-status is controlled by the worst index status.
-
-One of the main benefits of the API is the ability to wait until the
-cluster reaches a certain high water-mark health level. For example, the
-following will wait for 50 seconds for the cluster to reach the `yellow`
-level (if it reaches the `green` or `yellow` status before 50 seconds elapse,
-it will return at that point):
-
-[source,js]
---------------------------------------------------
-GET /_cluster/health?wait_for_status=yellow&timeout=50s
---------------------------------------------------
-// CONSOLE
-
-[float]
-[[request-params]]
-==== Request Parameters
-
-The cluster health API accepts the following request parameters:
-
-`level`::
-    Can be one of `cluster`, `indices` or `shards`. Controls the
-    details level of the health information returned. Defaults to `cluster`.
-
-`wait_for_status`::
-    One of `green`, `yellow` or `red`. Will wait (until
-    the timeout provided) until the status of the cluster changes to the one
-    provided or better, i.e. `green` > `yellow` > `red`. By default, will not
-    wait for any status.
-
-`wait_for_no_relocating_shards`::
-    A boolean value which controls whether to wait (until the timeout provided)
-    for the cluster to have no shard relocations. Defaults to false, which means
-    it will not wait for relocating shards.
-
-`wait_for_no_initializing_shards`::
-    A boolean value which controls whether to wait (until the timeout provided)
-    for the cluster to have no shard initializations. Defaults to false, which means
-    it will not wait for initializing shards.
-
-`wait_for_active_shards`::
-    A number controlling to how many active shards to wait for, `all` to wait
-    for all shards in the cluster to be active, or `0` to not wait. Defaults to `0`.
-
-`wait_for_nodes`::
-    The request waits until the specified number `N` of
-    nodes is available. It also accepts `>=N`, `<=N`, `>N` and `<N`.
-    Alternatively, it is possible to use `ge(N)`, `le(N)`, `gt(N)` and
-    `lt(N)` notation.
-
-`wait_for_events`::
-    Can be one of `immediate`, `urgent`, `high`, `normal`, `low`, `languid`.
-    Wait until all currently queued events with the given priority are processed.
-
-`timeout`::
-    A time based parameter controlling how long to wait if one of
-    the wait_for_XXX are provided. Defaults to `30s`.
-
-`master_timeout`::
-    A time based parameter controlling how long to wait if the master has not been
-    discovered yet or disconnected.
-    If not provided, uses the same value as `timeout`.
-
-`local`::
-    If `true` returns the local node information and does not provide
-    the state from master node. Default: `false`.
-
-
 The following is an example of getting the cluster health at the
 `shards` level: