From adaa54c06636cb0be73a088f0239e41d1cf10c5d Mon Sep 17 00:00:00 2001
From: James Rodewig <james.rodewig@elastic.co>
Date: Mon, 5 Aug 2019 11:17:37 -0400
Subject: [PATCH] [DOCS] Reformats cat allocation API (#45158)

---
 docs/reference/cat/allocation.asciidoc        | 43 ++++++++++++++++---
 docs/reference/rest-api/common-parms.asciidoc | 11 +++++
 2 files changed, 48 insertions(+), 6 deletions(-)

diff --git a/docs/reference/cat/allocation.asciidoc b/docs/reference/cat/allocation.asciidoc
index e1aeecb8c95..5d691e81a1f 100644
--- a/docs/reference/cat/allocation.asciidoc
+++ b/docs/reference/cat/allocation.asciidoc
@@ -1,8 +1,41 @@
 [[cat-allocation]]
 === cat allocation
 
-`allocation` provides a snapshot of how many shards are allocated to each data node
-and how much disk space they are using.
+Provides a snapshot of the number of shards allocated to each data node
+and their disk space.
+
+
+[[cat-allocation-api-request]]
+==== {api-request-title}
+
+`GET /_cat/allocation/{node_id}`
+
+[[cat-allocation-api-path-params]]
+==== {api-path-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=node-id]
+
+[[cat-allocation-api-query-params]]
+==== {api-query-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=bytes]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=http-format]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=local]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-h]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=help]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-s]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-v]
+
+[[cat-allocation-api-example]]
+==== {api-examples-title}
 
 [source,js]
 --------------------------------------------------
@@ -11,7 +44,7 @@ GET /_cat/allocation?v
 // CONSOLE
 // TEST[s/^/PUT test\n{"settings": {"number_of_replicas": 0}}\n/]
 
-Might respond with:
+The API returns the following response:
 
 [source,txt]
 --------------------------------------------------
@@ -21,6 +54,4 @@ shards disk.indices disk.used disk.avail disk.total disk.percent host      ip
 // TESTRESPONSE[s/\d+(\.\d+)?[tgmk]?b/\\d+(\\.\\d+)?[tgmk]?b/ s/46/\\d+/]
 // TESTRESPONSE[s/CSUXak2/.+/ non_json]
 
-Here we can see that the single shard created has been allocated to the single
-node available.
-
+This response shows a single shard is allocated to the one node available.
diff --git a/docs/reference/rest-api/common-parms.asciidoc b/docs/reference/rest-api/common-parms.asciidoc
index 708bc375627..f8d6fb39d38 100644
--- a/docs/reference/rest-api/common-parms.asciidoc
+++ b/docs/reference/rest-api/common-parms.asciidoc
@@ -1,4 +1,9 @@
 
+tag::bytes[]
+`bytes`::
+(Optional, <<byte-units,byte size units>>) Unit used to display byte values.
+end::bytes[]
+
 tag::cat-h[]
 `h` (headings)::
 (Optional, string) Comma-separated list of column names to display.
@@ -29,6 +34,12 @@ tag::name[]
 (Optional, string) Comma-separated list of alias names to return.
 end::name[]
 
+tag::node-id[]
+`{node_id}`::
+(Optional, string) Comma-separated list of node IDs or names used to limit
+returned information.
+end::node-id[]
+
 tag::cat-s[]
 `s` (sort)::
 (Optional, string) Comma-separated list of column names or column aliases used