Adding documentation for _list APIs (opensearch-project#8594)

* Adding documentation for _list APIs Signed-off-by: Harsh Garg <[email protected]> * Add edits to index page. Signed-off-by: Naarcha-AWS <[email protected]> * Add edits to list indices Signed-off-by: Naarcha-AWS <[email protected]> * Update list-shards.md Signed-off-by: Naarcha-AWS <[email protected]> * Update index.md Signed-off-by: Naarcha-AWS <[email protected]> * Small grammar fixes Signed-off-by: Naarcha-AWS <[email protected]> * Apply suggestions from code review Signed-off-by: Naarcha-AWS <[email protected]> * Apply suggestions from code review Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Naarcha-AWS <[email protected]> * Update _api-reference/list/list-indices.md Signed-off-by: Naarcha-AWS <[email protected]> * Update _api-reference/list/list-shards.md Signed-off-by: Naarcha-AWS <[email protected]> * Correcting the examples and limits for size parameter Signed-off-by: Harsh Garg <[email protected]> * Apply suggestions from code review Signed-off-by: Naarcha-AWS <[email protected]> * Update list-indices.md Signed-off-by: Naarcha-AWS <[email protected]> * Update list-shards.md Signed-off-by: Naarcha-AWS <[email protected]> * Apply suggestions from code review Signed-off-by: Naarcha-AWS <[email protected]> --------- Signed-off-by: Harsh Garg <[email protected]> Signed-off-by: Naarcha-AWS <[email protected]> Co-authored-by: Harsh Garg <[email protected]> Co-authored-by: Naarcha-AWS <[email protected]> Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Eric Pugh <[email protected]>
o19s · Nov 23, 2024 · a050b05 · a050b05
1 parent d03c4bb
commit a050b05
Show file tree

Hide file tree

Showing 3 changed files with 336 additions and 0 deletions.
diff --git a/_api-reference/list/index.md b/_api-reference/list/index.md
@@ -0,0 +1,175 @@
+---
+layout: default
+title: List API
+nav_order: 45
+has_children: true
+---
+
+# List APIs
+**Introduced 2.18**
+{: .label .label-purple }
+
+The List API retrieves statistics about indexes and shards in a paginated format. This streamlines the task of processing responses that include many indexes.
+
+The List API supports two operations:
+
+- [List indices]({{site.url}}{{site.baseurl}}/api-reference/list/list-indices/)
+- [List shards]({{site.url}}{{site.baseurl}}/api-reference/list/list-shards/)
+
+## Shared query parameters
+
+All List API operations support the following optional 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. 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` |  The format in which to return the result. Valid values are `json`, `yaml`, `cbor`, and `smile`.
+`s` | Sorts the output by the specified columns.
+
+## Examples
+
+The following examples show how to use the optional query parameters to customize all List API responses.
+
+
+### Get verbose output
+
+To query indexes and their statistics with a verbose output that includes all column headings in the response, use the `v` query parameter, as shown in the following example.
+
+#### Request
+
+```json
+GET _list/indices?v
+```
+{% include copy-curl.html %}
+
+#### Response
+
+```json
+health status index           uuid    pri rep  docs.count  docs.deleted
+green  open   .kibana_1 - - - -              
+yellow open    sample-index-1 - - - -
+next_token null
+```
+
+
+### Get all available headers
+
+To see all the available headers, use the `help` parameter with the following syntax:
+
+```json
+GET _list/<operation_name>?help
+```
+{% include copy-curl.html %}
+
+#### Request
+
+The following example list indices operation returns all the available headers:
+
+```json
+GET _list/indices?help
+```
+{% include copy-curl.html %}
+
+#### Response
+
+The following example displays the indexes and their health status in a table:
+
+```json
+health     | h                              | current health status
+status     | s                              | open/close status
+index      | i,idx                          | index name
+uuid       | id,uuid                        | index uuid
+pri        | p,shards.primary,shardsPrimary | number of primary shards
+rep        | r,shards.replica,shardsReplica | number of replica shards
+docs.count | dc,docsCount                   | available docs
+```
+
+### Get a subset of headers
+
+To limit the output to a subset of headers, use the `h` parameter with the following syntax:
+
+```json
+GET _list/<operation_name>?h=<header_name_1>,<header_name_2>&v
+```
+{% include copy-curl.html %}
+
+For any operation, you can determine which headers are available by using the `help` parameter and then using the `h` parameter to limit the output to only a subset of headers. 
+
+#### Request
+
+The following example limits the indexes in the response to only the index name and health status headers:
+
+```json
+GET _list/indices?h=health,index
+```
+{% include copy-curl.html %}
+
+### Response
+
+```json
+green  .kibana_1
+yellow sample-index-1
+next_token null
+```
+
+
+### Sort by a header
+
+To sort the output on a single page by a header, use the `s` parameter with the following syntax:
+
+```json
+GET _list/<operation_name>?s=<header_name_1>,<header_name_2>
+```
+{% include copy-curl.html %}
+
+#### Request
+
+The following example request sorts indexes by index name:
+
+```json
+GET _list/indices?s=h,i
+```
+{% include copy-curl.html %}
+
+#### Response
+
+```json
+green sample-index-2
+yellow sample-index-1
+next_token null
+```
+
+### Retrieve data in JSON format
+
+By default, List APIs return data in a `text/plain` format. Other supported formats are [YAML](https://yaml.org/), [CBOR](https://cbor.io/), and [Smile](https://github.com/FasterXML/smile-format-specification).
+
+
+To retrieve data in the JSON format, use the `format=json` parameter with the following syntax.
+
+If you use the Security plugin, ensure you have the appropriate permissions.
+{: .note }
+
+#### Request
+
+```json
+GET _list/<operation_name>?format=json
+```
+{% include copy-curl.html %}
+
+#### Request
+
+```json
+GET _list/indices?format=json
+```
+{% include copy-curl.html %}
+
+### Response
+
+The response contains data in JSON format:
+
+```json
+{"next_token":null,"indices":[{"health":"green","status":"-","index":".kibana_1","uuid":"-","pri":"-","rep":"-","docs.count":"-","docs.deleted":"-","store.size":"-","pri.store.size":"-"},{"health":"yellow","status":"-","index":"sample-index-1","uuid":"-","pri":"-","rep":"-","docs.count":"-","docs.deleted":"-","store.size":"-","pri.store.size":"-"}]}
+```
+
diff --git a/_api-reference/list/list-indices.md b/_api-reference/list/list-indices.md
@@ -0,0 +1,83 @@
+---
+layout: default
+title: List indices 
+parent: List API
+nav_order: 25
+has_children: false
+---
+
+# List indices
+**Introduced 2.18**
+{: .label .label-purple }
+
+The list indices operation provides the following index information in a paginated format: 
+
+- The amount of disk space used by the index. 
+- The number of shards contained in the index. 
+- The index's health status.
+
+## Path and HTTP methods
+
+```json
+GET _list/indices
+GET _list/indices/<index>
+```
+
+## Query parameters
+
+Parameter | Type | Description
+:--- | :--- | :---
+`bytes` | Byte size | Specifies the units for the byte size, for example, `7kb` or `6gb`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
+`health` | String | Limits indexes based on their health status. Supported values are `green`, `yellow`, and `red`.
+`include_unloaded_segments` | Boolean | Whether to include information from segments not loaded into memory. Default is `false`.
+`cluster_manager_timeout` | Time | The amount of time to wait for a connection to the cluster manager node. Default is `30s`.
+`pri` | Boolean | Whether to return information only from the primary shards. Default is `false`.
+`time` | Time | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
+`expand_wildcards` | Enum | Expands wildcard expressions to concrete indexes. Combine multiple values with commas. Supported values are `all`, `open`, `closed`, `hidden`, and `none`. Default is `open`.
+`next_token` | String | Fetches the next page of indexes. When `null`, only provides the first page of indexes. Default is `null`. 
+`size` | Integer | The maximum number of indexes to be displayed on a single page. The number of indexes on a single page of the response is not always equal to the specified `size`. Default is `500`. Minimum is `1` and maximum value is `5000`.
+`sort` | String | The order in which the indexes are displayed. If `desc`, then the most recently created indexes are displayed first. If `asc`, then the oldest indexes are displayed first. Default is `asc`.
+
+When using the `next_token` path parameter, use the token produced by the response to see the next page of indexes. After the API returns `null`, all indexes contained in the API have been returned.
+{: .tip }
+
+
+## Example requests
+
+To get information for all the indexes, use the following query and keep specifying the `next_token` as received from response until its `null`:
+
+```json
+GET _list/indices/<index>?v&next_token=token
+```
+
+
+To limit the information to a specific index, add the index name after your query, as shown in the following example:
+
+```json
+GET _list/indices/<index>?v
+```
+{% include copy-curl.html %}
+
+To get information about more than one index, separate the indexes with commas, as shown in the following example:
+
+```json
+GET _list/indices/index1,index2,index3?v&next_token=token
+```
+{% include copy-curl.html %}
+
+
+## Example response
+
+**Plain text format**
+
+```json
+health | status | index | uuid | pri | rep | docs.count | docs.deleted | store.size | pri.store.size
+green  | open | movies | UZbpfERBQ1-3GSH2bnM3sg | 1 | 1 | 1 | 0 | 7.7kb | 3.8kb
+next_token MTcyOTE5NTQ5NjM5N3wub3BlbnNlYXJjaC1zYXAtbG9nLXR5cGVzLWNvbmZpZw==
+```
+
+**JSON format**
+
+```json
+{"next_token":"MTcyOTE5NTQ5NjM5N3wub3BlbnNlYXJjaC1zYXAtbG9nLXR5cGVzLWNvbmZpZw==","indices":[{"health":"green","status":"open","index":"movies","uuid":"UZbpfERBQ1-3GSH2bnM3sg","pri":"1","rep":"1","docs.count":"1","docs.deleted":"0","store.size":"7.7kb","pri.store.size":"3.8kb"}]}
+```
diff --git a/_api-reference/list/list-shards.md b/_api-reference/list/list-shards.md
@@ -0,0 +1,78 @@
+---
+layout: default
+title: List shards
+parent: List API
+nav_order: 20
+---
+
+# List shards
+**Introduced 2.18**
+{: .label .label-purple }
+
+The list shards operation outputs, in a paginated format, the state of all primary and replica shards and how they are distributed.
+
+## Path and HTTP methods
+
+```json
+GET _list/shards
+GET _list/shards/<index>
+```
+
+## Query parameters
+
+All parameters are optional.
+
+Parameter | Type | Description
+:--- | :--- | :---
+`bytes` | Byte size | Specifies the byte size units, for example, `7kb` or `6gb`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
+`local` | Boolean | Whether to return information from the local node only instead of from the cluster manager node. Default is `false`.
+`cluster_manager_timeout` | Time | The amount of time to wait for a connection to the cluster manager node. Default is `30s`.
+`cancel_after_time_interval` | Time | The amount of time after which the shard request is canceled. Default is `-1` (no timeout).
+`time` | Time | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
+`next_token` | String | Fetches the next page of indexes. When `null`, only provides the first page of indexes. Default is `null`.
+`size` | Integer | The maximum number of indexes to be displayed on a single page. The number of indexes on a single page of the response is not always equal to the specified `size`. Default and minimum value is `2000`. Maximum value is `20000`.
+`sort` | String | The order in which the indexes are displayed. If `desc`, then the most recently created indexes are displayed first. If `asc`, then the oldest indexes are displayed first. Default is `asc`.
+
+When using the `next_token` path parameter, use the token produced by the response to see the next page of indexes. After the API returns `null`, all indexes contained in the API have been returned.
+{: .tip }
+
+## Example requests
+
+To get information for all the indexes and shards, use the following query and keep specifying the `next_token` as received from response until its `null`:
+
+```json
+GET _list/shards/<index>?v&next_token=token
+```
+
+To limit the information to a specific index, add the index name after your query, as shown in the following example and keep specifying the `next_token` as received from response until its `null`:
+
+```json
+GET _list/shards/<index>?v&next_token=token
+```
+{% include copy-curl.html %}
+
+If you want to get information for more than one index, separate the indexes with commas, as shown in the following example:
+
+```json
+GET _list/shards/index1,index2,index3?v&next_token=token
+```
+{% include copy-curl.html %}
+
+## Example response
+
+**Plain text format**
+
+```json
+index | shard | prirep | state   | docs | store | ip |       | node
+plugins | 0   |   p    | STARTED |   0  |  208b | 172.18.0.4 | odfe-node1
+plugins | 0   |   r    | STARTED |   0  |  208b | 172.18.0.3 |  odfe-node2
+....
+....
+next_token MTcyOTE5NTQ5NjM5N3wub3BlbnNlYXJjaC1zYXAtbG9nLXR5cGVzLWNvbmZpZw==   
+```
+
+**JSON format**
+
+```json
+{"next_token":"MTcyOTE5NTQ5NjM5N3wub3BlbnNlYXJjaC1zYXAtbG9nLXR5cGVzLWNvbmZpZw==","shards":[{"index":"plugins","shard":"0","prirep":"p","state":"STARTED","docs":"0","store":"208B","ip":"172.18.0.4","node":"odfe-node1"},{"index":"plugins","shard":"0","prirep":"r","state":"STARTED","docs":"0","store":"208B","ip":"172.18.0.3","node":"odfe-node2"}]}
+```