From 8142ca82f193c851f6697acd889c4be7575f37d3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?=
 <istvan.szabo@elastic.co>
Date: Wed, 14 Aug 2019 18:19:05 +0200
Subject: [PATCH] [DOCS] Reformats nodes feature usage API (#45539)

Co-Authored-By: James Rodewig <james.rodewig@elastic.co>
---
 docs/reference/cluster/nodes-usage.asciidoc | 72 +++++++++++++++------
 1 file changed, 53 insertions(+), 19 deletions(-)

diff --git a/docs/reference/cluster/nodes-usage.asciidoc b/docs/reference/cluster/nodes-usage.asciidoc
index 06473d3380f..dad18afc05f 100644
--- a/docs/reference/cluster/nodes-usage.asciidoc
+++ b/docs/reference/cluster/nodes-usage.asciidoc
@@ -1,33 +1,67 @@
 [[cluster-nodes-usage]]
 === Nodes Feature Usage
 
-[float]
-==== Nodes usage
+Returns information on the usage of features.
 
-The cluster nodes usage API allows to retrieve information on the usage
-of features for each node.
+
+[[cluster-nodes-usage-api-request]]
+==== {api-request-title}
+
+`GET /_nodes/usage` +
+
+`GET /_nodes/{node_id}/usage` +
+
+`GET /_nodes/usage/{metric}` +
+
+`GET /_nodes/{node_id}/usage/{metric}`
+
+
+[[cluster-nodes-usage-api-desc]]
+==== {api-description-title}
+
+The cluster nodes usage API allows you to retrieve information on the usage
+of features for each node. All the nodes selective options are explained
+<<cluster-nodes,here>>.
+
+
+[[cluster-nodes-usage-api-path-params]]
+==== {api-path-parms-title}
+
+`{metric}`::
+    (Optional, string) Limits the information returned to the specific metrics. 
+    A comma-separated list of the following options: 
++
+--
+    `_all`::
+        Returns all stats.
+    
+    `rest_actions`::
+        Returns the REST actions classname with a count of the number of times 
+        that action has been called on the node.
+--
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=node-id]
+
+
+[[cluster-nodes-usage-api-query-params]]
+==== {api-query-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
+
+
+[[cluster-nodes-usage-api-example]]
+==== {api-examples-title}
+
+Rest action example:
 
 [source,js]
 --------------------------------------------------
 GET _nodes/usage
-GET _nodes/nodeId1,nodeId2/usage
 --------------------------------------------------
 // CONSOLE
 // TEST[setup:node]
-// TEST[s/nodeId1,nodeId2/*/]
 
-The first command retrieves usage of all the nodes in the cluster. The
-second command selectively retrieves nodes usage of only `nodeId1` and
-`nodeId2`. All the nodes selective options are explained
-<<cluster-nodes,here>>.
-
-[float]
-[[rest-usage]]
-===== REST actions usage information
-
-The `rest_actions` field in the response contains a map of the REST
-actions classname with a count of the number of times that action has
-been called on the node:
+The API returns the following response:
 
 [source,js]
 --------------------------------------------------
@@ -61,4 +95,4 @@ been called on the node:
 <1> Timestamp for when this nodes usage request was performed.
 <2> Timestamp for when the usage information recording was started. This is
 equivalent to the time that the node was started.
-<3> Search action has been called 19 times for this node.
\ No newline at end of file
+<3> Search action has been called 19 times for this node.