From d9996bfdae415e81b51ccac510c3b224f2a1deb8 Mon Sep 17 00:00:00 2001
From: dblock <dblock@amazon.com>
Date: Tue, 2 Jul 2024 18:49:35 -0400
Subject: [PATCH] Added documentation for cat?sort and format.

Signed-off-by: dblock <dblock@amazon.com>
---
 _api-reference/cat/index.md | 118 ++++++++++++++++++++++++++++++++++--
 1 file changed, 114 insertions(+), 4 deletions(-)

diff --git a/_api-reference/cat/index.md b/_api-reference/cat/index.md
index 0ddaf1e0a7..72cc7d7d60 100644
--- a/_api-reference/cat/index.md
+++ b/_api-reference/cat/index.md
@@ -24,17 +24,54 @@ GET _cat
 ```
 {% include copy-curl.html %}
 
+The response is an ASCII cat (`=^.^=`) and a list of operations.
+
+```
+=^.^=
+/_cat/allocation
+/_cat/segment_replication
+/_cat/segment_replication/{index}
+/_cat/shards
+/_cat/shards/{index}
+/_cat/cluster_manager
+/_cat/nodes
+/_cat/tasks
+/_cat/indices
+/_cat/indices/{index}
+/_cat/segments
+/_cat/segments/{index}
+/_cat/count
+/_cat/count/{index}
+/_cat/recovery
+/_cat/recovery/{index}
+/_cat/health
+/_cat/pending_tasks
+/_cat/aliases
+/_cat/aliases/{alias}
+/_cat/thread_pool
+/_cat/thread_pool/{thread_pools}
+/_cat/plugins
+/_cat/fielddata
+/_cat/fielddata/{fields}
+/_cat/nodeattrs
+/_cat/repositories
+/_cat/snapshots/{repository}
+/_cat/templates
+/_cat/pit_segments
+/_cat/pit_segments/{pit_id}
+```
+
 ## Optional query parameters
 
-You can use the following query parameters with any CAT API to filter your results.
+The root `_cat` API does not take any parameters, but individual APIs, such as `/_cat/nodes` accept the following query parameters.
 
 Parameter | Description
 :--- | :--- |
 `v` |  Provides verbose output by adding headers to the columns. It also adds some formatting to help align each of the columns together. All examples in this section include the `v` parameter.
 `help` | Lists the default and other available headers for a given operation.
 `h`  |  Limits the output to specific headers.
-`format` |  Returns the result in JSON, YAML, or CBOR formats.
-`sort` | Sorts the output by the specified columns.
+`format` |  Returns the result in JSON, YAML, CBOR, or SMILE formats.
+`s` | Sorts the output by the specified columns.
 
 ### Query parameter usage examples
 
@@ -59,7 +96,6 @@ sample-alias1 sample-index-1 - - - -
 Without the verbose parameter, `v`, the response simply returns the alias names:
 
 ```
-
 .kibana .kibana_1 - - - -
 sample-alias1 sample-index-1 - - - -
 ```
@@ -72,6 +108,22 @@ To see all the available headers, use the `help` parameter:
 GET _cat/<operation_name>?help
 ```
 
+For example, the aliases help contains all available headers.
+
+```json
+GET _cat/aliases?help
+```
+{% include copy-curl.html %}
+
+```
+alias          | a                | alias name
+index          | i,idx            | index alias points to
+filter         | f,fi             | filter
+routing.index  | ri,routingIndex  | index routing
+routing.search | rs,routingSearch | search routing
+is_write_index | w,isWriteIndex   | write index
+```
+
 ### Get a subset of headers
 
 To limit the output to a subset of headers, use the `h` parameter:
@@ -80,7 +132,65 @@ To limit the output to a subset of headers, use the `h` parameter:
 GET _cat/<operation_name>?h=<header_name_1>,<header_name_2>&v
 ```
 
+For example, to limit aliases to only the alias name and index.
+
+```json
+GET _cat/aliases?h=alias,index
+```
+{% include copy-curl.html %}
+
+```
+.kibana .kibana_1
+sample-alias1 sample-index-1
+```
+
 Typically, for any operation you can find out what headers are available using the `help` parameter, and then use the `h` parameter to limit the output to only the headers that you care about.
 
+### Sort by a header
+
+To sort the output by a header, use the `s` parameter:
+
+```
+GET _cat/<operation_name>?s=<header_name_1>,<header_name_2>
+```
+
+For example, to sort aliases by alias then index.
+
+```json
+GET _cat/aliases?s=i,a
+```
+{% include copy-curl.html %}
+
+```
+sample-alias2 sample-index-1
+sample-alias1 sample-index-2
+```
+
+### Retrieve data in JSON format
+
+By default the CAT APIs return `text/plain` data.
+
+To retrieve data in the JSON format, use the `format=json` parameter:
+
+```
+GET _cat/<operation_name>?format=json
+```
+
+For example, to retrieve aliases in JSON format.
+
+```json
+GET _cat/aliases?format=json
+```
+{% include copy-curl.html %}
+
+```json
+[
+  {"alias":".kibana","index":".kibana_1","filter":"-","routing.index":"-","routing.search":"-","is_write_index":"-"},
+  {"alias":"sample-alias-1","index":"sample-index-1","filter":"-","routing.index":"-","routing.search":"-","is_write_index":"-"}
+]
+```
+
+Other supported formats are [YAML](https://yaml.org/), [CBOR](https://cbor.io/) and [Smile](https://github.com/FasterXML/smile-format-specification).
+
 If you use the Security plugin, make sure you have the appropriate permissions.
 {: .note }