[Proposal] Update API template (#7709) (#7827)

opensearch-project · Jul 24, 2024 · 56c61b2 · 56c61b2
1 parent 3c29b8c
commit 56c61b2
Show file tree

Hide file tree

Showing 75 changed files with 552 additions and 543 deletions.
diff --git a/API_STYLE_GUIDE.md b/API_STYLE_GUIDE.md
@@ -115,7 +115,7 @@ Include a table with these columns:
 Field | Data type | Description
 :--- | :--- | :--- 
 
-#### Example request
+## Example request
 
 Provide a sentence that describes what is shown in the example, followed by a cut-and-paste-ready API request in JSON format. Make sure that you test the request yourself in the Dashboards Dev Tools console to make sure it works. See the following examples.
 
@@ -139,7 +139,7 @@ POST _reindex
 }
 ```
 
-#### Example response
+## Example response
 
 Include a JSON example response to show what the API returns. See the following examples.
 

diff --git a/_api-reference/analyze-apis.md b/_api-reference/analyze-apis.md
@@ -61,7 +61,7 @@ Field | Data type | Description
 :--- | :--- | :---
 text | String or Array of Strings | Text to analyze. If you provide an array of strings, the text is analyzed as a multi-value field.
 
-#### Example requests
+## Example requests
 
 [Analyze array of text strings](#analyze-array-of-text-strings)
 

diff --git a/_api-reference/cat/cat-aliases.md b/_api-reference/cat/cat-aliases.md
@@ -15,26 +15,6 @@ has_children: false
 
 The CAT aliases operation lists the mapping of aliases to indexes, plus routing and filtering information.
 
-## Example
-
-```json
-GET _cat/aliases?v
-```
-{% include copy-curl.html %}
-
-To limit the information to a specific alias, add the alias name after your query:
-
-```json
-GET _cat/aliases/<alias>?v
-```
-{% include copy-curl.html %}
-
-If you want to get information for more than one alias, separate the alias names with commas:
-
-```json
-GET _cat/aliases/alias1,alias2,alias3
-```
-{% include copy-curl.html %}
 
 ## Path and HTTP methods
 
@@ -55,7 +35,28 @@ Parameter | Type | Description
 local | Boolean | Whether to return information from the local node only instead of from the cluster manager node. Default is `false`.
 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`.
 
-## Response
+## Example requests
+
+```json
+GET _cat/aliases?v
+```
+{% include copy-curl.html %}
+
+To limit the information to a specific alias, add the alias name after your query:
+
+```json
+GET _cat/aliases/<alias>?v
+```
+{% include copy-curl.html %}
+
+If you want to get information for more than one alias, separate the alias names with commas:
+
+```json
+GET _cat/aliases/alias1,alias2,alias3
+```
+{% include copy-curl.html %}
+
+## Example response
 
 The following response shows that `alias1` refers to a `movies` index and has a configured filter:
 

diff --git a/_api-reference/cat/cat-allocation.md b/_api-reference/cat/cat-allocation.md
@@ -14,26 +14,6 @@ has_children: false
 
 The CAT allocation operation lists the allocation of disk space for indexes and the number of shards on each node.
 
-## Example
-
-```json
-GET _cat/allocation?v
-```
-{% include copy-curl.html %}
-
-To limit the information to a specific node, add the node name after your query:
-
-```json
-GET _cat/allocation/<node_name>
-```
-{% include copy-curl.html %}
-
-If you want to get information for more than one node, separate the node names with commas:
-
-```json
-GET _cat/allocation/node_name_1,node_name_2,node_name_3
-```
-{% include copy-curl.html %}
 
 ## Path and HTTP methods
 
@@ -54,7 +34,28 @@ bytes | Byte size | Specify the units for byte size. For example, `7kb` or `6gb`
 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 30 seconds.
 
-## Response
+## Example requests
+
+```json
+GET _cat/allocation?v
+```
+{% include copy-curl.html %}
+
+To limit the information to a specific node, add the node name after your query:
+
+```json
+GET _cat/allocation/<node_name>
+```
+{% include copy-curl.html %}
+
+If you want to get information for more than one node, separate the node names with commas:
+
+```json
+GET _cat/allocation/node_name_1,node_name_2,node_name_3
+```
+{% include copy-curl.html %}
+
+## Example response
 
 The following response shows that eight shards are allocated to each of the two nodes available:
 

diff --git a/_api-reference/cat/cat-cluster_manager.md b/_api-reference/cat/cat-cluster_manager.md
@@ -14,12 +14,6 @@ has_children: false
 
 The CAT cluster manager operation lists information that helps identify the elected cluster manager node.
 
-## Example
-
-```
-GET _cat/cluster_manager?v
-```
-{% include copy-curl.html %}
 
 ## Path and HTTP methods
 
@@ -37,7 +31,14 @@ Parameter | Type | Description
 :--- | :--- | :---
 cluster_manager_timeout | Time | The amount of time to wait for a connection to the cluster manager node. Default is 30 seconds.
 
-## Response
+## Example requests
+
+```
+GET _cat/cluster_manager?v
+```
+{% include copy-curl.html %}
+
+## Example response
 
 ```json
 id                     |   host     |     ip     |   node

diff --git a/_api-reference/cat/cat-count.md b/_api-reference/cat/cat-count.md
@@ -15,7 +15,19 @@ redirect_from:
 
 The CAT count operation lists the number of documents in your cluster.
 
-## Example
+
+## Path and HTTP methods
+
+```
+GET _cat/count?v
+GET _cat/count/<index>?v
+```
+
+## URL parameters
+
+All CAT count URL parameters are optional. You can specify any of the [common URL parameters]({{site.url}}{{site.baseurl}}/api-reference/cat/index).
+
+## Example requests
 
 ```json
 GET _cat/count?v
@@ -36,19 +48,7 @@ GET _cat/count/index_or_alias_1,index_or_alias_2,index_or_alias_3
 ```
 {% include copy-curl.html %}
 
-## Path and HTTP methods
-
-```
-GET _cat/count?v
-GET _cat/count/<index>?v
-```
-
-## URL parameters
-
-All CAT count URL parameters are optional. You can specify any of the [common URL parameters]({{site.url}}{{site.baseurl}}/api-reference/cat/index).
-
-
-## Response
+## Example response
 
 The following response shows the overall document count as 1625:
 

diff --git a/_api-reference/cat/cat-field-data.md b/_api-reference/cat/cat-field-data.md
@@ -8,13 +8,31 @@ redirect_from:
 - /opensearch/rest-api/cat/cat-field-data/
 ---
 
-# CAT fielddata
+# CAT Field Data
 **Introduced 1.0**
 {: .label .label-purple }
 
-The CAT fielddata operation lists the memory size used by each field per node.
+The CAT Field Data operation lists the memory size used by each field per node.
 
-## Example
+
+## Path and HTTP methods
+
+```
+GET _cat/fielddata?v
+GET _cat/fielddata/<field_name>?v
+```
+
+## URL parameters
+
+All CAT fielddata URL parameters are optional.
+
+In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/api-reference/cat/index), you can specify the following parameter:
+
+Parameter | Type | Description
+:--- | :--- | :---
+bytes | Byte size | Specify the units for byte size. For example, `7kb` or `6gb`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
+
+## Example requests
 
 ```json
 GET _cat/fielddata?v
@@ -35,24 +53,7 @@ GET _cat/fielddata/field_name_1,field_name_2,field_name_3
 ```
 {% include copy-curl.html %}
 
-## Path and HTTP methods
-
-```
-GET _cat/fielddata?v
-GET _cat/fielddata/<field_name>?v
-```
-
-## URL parameters
-
-All CAT fielddata URL parameters are optional.
-
-In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/api-reference/cat/index), you can specify the following parameter:
-
-Parameter | Type | Description
-:--- | :--- | :---
-bytes | Byte size | Specify the units for byte size. For example, `7kb` or `6gb`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
-
-## Response
+## Example response
 
 The following response shows the memory size for all fields as 284 bytes:
 

diff --git a/_api-reference/cat/cat-health.md b/_api-reference/cat/cat-health.md
@@ -15,12 +15,6 @@ redirect_from:
 
 The CAT health operation lists the status of the cluster, how long the cluster has been up, the number of nodes, and other useful information that helps you analyze the health of your cluster.
 
-## Example
-
-```json
-GET _cat/health?v
-```
-{% include copy-curl.html %}
 
 ## Path and HTTP methods
 
@@ -38,7 +32,15 @@ Parameter | Type | Description
 time | Time | Specify the units for time. For example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
 ts | Boolean | If true, returns HH:MM:SS and Unix epoch timestamps. Default is `true`.
 
-## Response
+## Example request
+
+The following example request give cluster health information for the past 5 days: 
+
+```json
+GET _cat/health?v&time=5d
+```
+
+## Example response
 
 ```json
 GET _cat/health?v&time=5d

diff --git a/_api-reference/cat/cat-indices.md b/_api-reference/cat/cat-indices.md
@@ -14,26 +14,6 @@ redirect_from:
 
 The CAT indices operation lists information related to indexes, that is, how much disk space they are using, how many shards they have, their health status, and so on.
 
-## Example
-
-```
-GET _cat/indices?v
-```
-{% include copy-curl.html %}
-
-To limit the information to a specific index, add the index name after your query.
-
-```
-GET _cat/indices/<index>?v
-```
-{% include copy-curl.html %}
-
-If you want to get information for more than one index, separate the indexes with commas:
-
-```json
-GET _cat/indices/index1,index2,index3
-```
-{% include copy-curl.html %}
 
 ## Path and HTTP methods
 
@@ -58,8 +38,29 @@ pri | Boolean | Whether to return information only from the primary shards. Defa
 time | Time | Specify the units for time. 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`.
 
+## Example requests
+
+```
+GET _cat/indices?v
+```
+{% include copy-curl.html %}
+
+To limit the information to a specific index, add the index name after your query.
+
+```
+GET _cat/indices/<index>?v
+```
+{% include copy-curl.html %}
+
+If you want to get information for more than one index, separate the indexes with commas:
+
+```json
+GET _cat/indices/index1,index2,index3
+```
+{% include copy-curl.html %}
+
 
-## Response
+## Example response
 
 ```json
 health | status | index | uuid | pri | rep | docs.count | docs.deleted | store.size | pri.store.size

diff --git a/_api-reference/cat/cat-nodeattrs.md b/_api-reference/cat/cat-nodeattrs.md
@@ -14,12 +14,6 @@ redirect_from:
 
 The CAT nodeattrs operation lists the attributes of custom nodes.
 
-## Example
-
-```
-GET _cat/nodeattrs?v
-```
-{% include copy-curl.html %}
 
 ## Path and HTTP methods
 
@@ -38,8 +32,17 @@ Parameter | Type | Description
 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 30 seconds.
 
+## Example request
+
+The following example request returns attributes about custom nodes:
+
+```
+GET _cat/nodeattrs?v
+```
+{% include copy-curl.html %}
+
 
-## Response
+## Example response
 
 ```json
 node | host | ip | attr | value