Refactor snapshot documentation (#10303) (#10307)

opensearch-trigger-bot[bot] · github-actions[bot] · natebower · web-flow · commit c60f59087250 · 2025-07-16T10:21:18.000-04:00
* Refactor snapshot documentation * Apply suggestions from code review * Add redirect to index page --------- (cherry picked from commit 178e536) Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> Signed-off-by: Nathan Bower <nbower@amazon.com> Signed-off-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> Co-authored-by: Nathan Bower <nbower@amazon.com>
diff --git a/_api-reference/snapshots/cleanup-snapshot-repository.md b/_api-reference/snapshots/cleanup-snapshot-repository.md
@@ -1,11 +1,11 @@
 ---
 layout: default
-title: Cleanup Snapshot Repository
+title: Cleanup snapshot repository
 parent: Snapshot APIs
 nav_order: 11
 ---
 
-# Cleanup Snapshot Repository 
+# Cleanup snapshot repository 
 Introduced 1.0
 {: .label .label-purple }
 
diff --git a/_api-reference/snapshots/create-repository.md b/_api-reference/snapshots/create-repository.md
@@ -1,6 +1,6 @@
 ---
 layout: default
-title: Register Snapshot Repository
+title: Register snapshot repository
 parent: Snapshot APIs
 nav_order: 1
 ---
diff --git a/_api-reference/snapshots/create-snapshot.md b/_api-reference/snapshots/create-snapshot.md
@@ -11,9 +11,9 @@ nav_order: 5
 
 Creates a snapshot within an existing repository.
 
-* To learn more about snapshots, see [Snapshots]({{site.url}}{{site.baseurl}}/opensearch/snapshots/index).
+* To learn more about snapshots, see [Snapshots]({{site.url}}{{site.baseurl}}/opensearch/snapshots/index/).
 
-* To view a list of your repositories, see [Get snapshot repository]({{site.url}}{{site.baseurl}}/api-reference/snapshots/get-snapshot-repository).
+* To view a list of your repositories, see [Get snapshot repository]({{site.url}}{{site.baseurl}}/api-reference/snapshots/get-snapshot-repository/).
 
 ## Endpoints
 
diff --git a/_api-reference/snapshots/delete-snapshot-repository.md b/_api-reference/snapshots/delete-snapshot-repository.md
@@ -1,6 +1,6 @@
 ---
 layout: default
-title: Delete Snapshot Repository
+title: Delete snapshot repository
 parent: Snapshot APIs
 nav_order: 3
 ---
diff --git a/_api-reference/snapshots/delete-snapshot.md b/_api-reference/snapshots/delete-snapshot.md
@@ -1,6 +1,6 @@
 ---
 layout: default
-title: Delete Snapshot
+title: Delete snapshot
 parent: Snapshot APIs
 nav_order: 7
 ---
diff --git a/_api-reference/snapshots/get-snapshot-repository.md b/_api-reference/snapshots/get-snapshot-repository.md
@@ -1,6 +1,6 @@
 ---
 layout: default
-title: Get Snapshot Repository
+title: Get snapshot repository
 parent: Snapshot APIs
 nav_order: 2
 ---
diff --git a/_api-reference/snapshots/get-snapshot-status.md b/_api-reference/snapshots/get-snapshot-status.md
@@ -1,6 +1,6 @@
 ---
 layout: default
-title: Get Snapshot Status
+title: Get snapshot status
 parent: Snapshot APIs
 nav_order: 8
 ---
diff --git a/_api-reference/snapshots/get-snapshot.md b/_api-reference/snapshots/get-snapshot.md
@@ -1,11 +1,11 @@
 ---
 layout: default
-title: Get Snapshot
+title: Get snapshot
 parent: Snapshot APIs
 nav_order: 6
 ---
 
-# Get snapshot.
+# Get snapshot
 **Introduced 1.0**
 {: .label .label-purple }
 
@@ -28,8 +28,8 @@ GET _snapshot/<repository>/<snapshot>/
 
 | Parameter | Data type | Description | 
 :--- | :--- | :---
-| verbose | Boolean | Whether to show all, or just basic snapshot information. If `true`, returns all information. If `false`, omits information like start/end times, failures, and shards. Optional, defaults to `true`.|
-| ignore_unavailable | Boolean | How to handle snapshots that are unavailable (corrupted or otherwise temporarily can't be returned). If `true` and the snapshot is unavailable, the request does not return the snapshot. If `false` and the snapshot is unavailable, the request returns an error. Optional, defaults to `false`.|
+| verbose | Boolean | When `true`, returns additional information about each snapshot, such as the version of OpenSearch that took the snapshot, the start and end times of the snapshot, and the number of shards contained in the snapshot. When `false`, returns only snapshot names and contained indexes. This is useful when the snapshots belong to a cloud-based repository, where each blob read is a cost or performance concern. Optional. Default is `true`.|
+| ignore_unavailable | Boolean | How to handle snapshots that are unavailable (corrupted or otherwise temporarily can't be returned). If `true` and the snapshot is unavailable, the request does not return the snapshot. If `false` and the snapshot is unavailable, the request returns an error. Optional. Default is `false`.|
 
 ## Example request
 
diff --git a/_api-reference/snapshots/index.md b/_api-reference/snapshots/index.md
@@ -6,6 +6,7 @@ nav_order: 80
 redirect_from:
   - /opensearch/rest-api/document-apis/
   - /opensearch/rest-api/snapshots/
+  - /api-reference/snapshots/
 ---
 
 # Snapshot APIs
diff --git a/_api-reference/snapshots/restore-snapshot.md b/_api-reference/snapshots/restore-snapshot.md
@@ -6,17 +6,17 @@ parent: Snapshot APIs
 nav_order: 9
 ---
 
-# Restore Snapshot
+# Restore snapshot
 **Introduced 1.0**
 {: .label .label-purple }
 
-Restores a snapshot of a cluster or specified data streams and indices. 
+Restores a snapshot of a cluster or specified data streams and indexes. 
 
-* For information about indices and clusters, see [Introduction to OpenSearch]({{site.url}}{{site.baseurl}}/opensearch/index).
+* For information about indexes and clusters, see [Introduction to OpenSearch]({{site.url}}{{site.baseurl}}/opensearch/index/).
 
 * For information about data streams, see [Data streams]({{site.url}}{{site.baseurl}}/opensearch/data-streams).
 
-If open indexes with the same name that you want to restore already exist in the cluster, you must close, delete, or rename the indexes. See [Example request](#example-request) for information about renaming an index. See [Close index]({{site.url}}{{site.baseurl}}/api-reference/index-apis/close-index) for information about closing an index.
+If open indexes with the same name that you want to restore already exist in the cluster, you must close, delete, or rename the indexes. See [Example request](#example-request) for information about renaming an index. See [Close index]({{site.url}}{{site.baseurl}}/api-reference/index-apis/close-index/) for information about closing an index.
 {: .note}
 
 ## Endpoints
@@ -56,7 +56,8 @@ All request body parameters are optional.
 | rename_alias_pattern | String | The pattern to apply to the restored aliases. Aliases matching the rename pattern will be renamed according to the `rename_alias_replacement` setting. <br /><br /> The rename pattern is applied as defined by the regular expression that supports referencing the original text. <br /> <br /> If two or more aliases are renamed to the same name, these aliases will be merged into one.|
 | rename_alias_replacement | String | The rename replacement string for aliases.|
 | source_remote_store_repository | String | The name of the remote store repository of the source index being restored. If not provided, the Snapshot Restore API will use the repository that was registered when the snapshot was created.
-| wait_for_completion | Boolean | Whether to return a response after the restore operation has completed.  If `false`, the request returns a response when the restore operation initializes.  If `true`, the request returns a response when the restore operation completes. Defaults to `false`. |
+| wait_for_completion | Boolean | Whether to return a response after the restore operation has completed. If `false`, the request returns a response when the restore operation initializes. If `true`, the request returns a response when the restore operation completes. Default is `false`. |
+storage_type | `local` indicates that all snapshot metadata and index data will be downloaded to local storage. <br /><br > `remote_snapshot` indicates that snapshot metadata will be downloaded to the cluster, but the remote repository will remain the authoritative store of the index data. Data will be downloaded and cached as necessary to service queries. At least one node in the cluster must be configured with the [search role]({{site.url}}{{site.baseurl}}/security/access-control/users-roles/) in order to restore a snapshot using the type `remote_snapshot`. <br /><br > Defaults to `local`.
 
 <sup>1</sup>The cluster state includes:
 * Persistent cluster settings
diff --git a/_api-reference/snapshots/verify-snapshot-repository.md b/_api-reference/snapshots/verify-snapshot-repository.md
@@ -1,8 +1,7 @@
 ---
 layout: default
-title: Verify Snaphot Repository
+title: Verify snaphot repository
 parent: Snapshot APIs
-
 nav_order: 4
 ---
 
diff --git a/_tuning-your-cluster/availability-and-recovery/snapshots/snapshot-restore.md b/_tuning-your-cluster/availability-and-recovery/snapshots/snapshot-restore.md
@@ -404,12 +404,7 @@ PUT /_snapshot/my-repository/2
 ```
 {% include copy-curl.html %}
 
-Request fields | Description
-:--- | :---
-`indices` | The indexes you want to include in the snapshot. You can use `,` to create a list of indexes, `*` to specify an index pattern, and `-` to exclude certain indexes. Don't put spaces between items. Default is all indexes.
-`ignore_unavailable` | If an index from the `indices` list doesn't exist, whether to ignore it rather than fail the snapshot. Default is `false`.
-`include_global_state` | Whether to include cluster state in the snapshot. Default is `true`.
-`partial` | Whether to allow partial snapshots. Default is `false`, which fails the entire snapshot if one or more shards fails to store.
+For more information, see [Create Snapshot API]({{site.url}}{{site.baseurl}}/api-reference/snapshots/create-snapshot/).
 
 If you request the snapshot immediately after taking it, you might see something like this:
 
@@ -433,6 +428,8 @@ GET /_snapshot/my-repository/2
 ```
 {% include copy-curl.html %}
 
+For more information, see [Get Snapshot API]({{site.url}}{{site.baseurl}}/api-reference/snapshots/get-snapshot/).
+
 Note that the snapshot is still in progress. If you want to wait for the snapshot to finish before continuing, add the `wait_for_completion` parameter to your request. Snapshots can take a while to complete, so consider whether or not this option fits your use case:
 
 ```
@@ -503,20 +500,7 @@ POST /_snapshot/my-repository/2/_restore
 ```
 {% include copy-curl.html %}
 
-Request parameters | Description
-:--- | :---
-`indices` | The indexes you want to restore. You can use `,` to create a list of indexes, `*` to specify an index pattern, and `-` to exclude certain indexes. Don't put spaces between items. Default is all indexes.
-`ignore_unavailable` | If an index from the `indices` list doesn't exist, whether to ignore it rather than fail the restore operation. Default is `false`.
-`include_global_state` | Whether to restore the cluster state. Default is `false`.
-`include_aliases` | Whether to restore aliases alongside their associated indexes. Default is `true`.
-`partial` | Whether to allow the restoration of partial snapshots. Default is `false`.
-`rename_pattern` | If you want to rename indexes, use this option to specify a regular expression that matches all the indexes that you want to restore and rename. Use capture groups (`()`) to reuse portions of the index name.
-`rename_replacement` | If you want to rename indexes, use this option to specify the name replacement pattern. Use `$0` to include the entire matching index name or the number of the capture group. For example, `$1` would include the content of the first capture group.
-`rename_alias_pattern` | If you want to rename aliases, use this option to specify a regular expression that matches all the aliases you want to restore and rename. Use capture groups (`()`) to reuse portions of the alias name.
-`rename_alias_replacement` | If you want to rename aliases, use this option to specify the name replacement pattern. Use `$0` to include the entire matching alias name or the number of the capture group. For example, `$1` would include the content of the first capture group.
-`index_settings` | If you want to change [index settings]({{site.url}}{{site.baseurl}}/im-plugin/index-settings/) applied during the restore operation, specify them here. You cannot change `index.number_of_shards`.
-`ignore_index_settings` | Rather than explicitly specifying new settings with `index_settings`, you can ignore certain index settings in the snapshot and use the cluster defaults applied during restore. You cannot ignore `index.number_of_shards`, `index.number_of_replicas`, or `index.auto_expand_replicas`.
-`storage_type` | `local` indicates that all snapshot metadata and index data will be downloaded to local storage. <br /><br > `remote_snapshot` indicates that snapshot metadata will be downloaded to the cluster, but the remote repository will remain the authoritative store of the index data. Data will be downloaded and cached as necessary to service queries. At least one node in the cluster must be configured with the [search role]({{site.url}}{{site.baseurl}}/security/access-control/users-roles/) in order to restore a snapshot using the type `remote_snapshot`. <br /><br > Defaults to `local`.
+For more information, see [Restore Snapshot API]({{site.url}}{{site.baseurl}}/api-reference/snapshots/restore-snapshot/).
 
 ### Conflicts and compatibility
 
@@ -567,3 +551,7 @@ We strongly recommend against restoring `.opendistro_security` using an admin ce
 ## Index codec considerations
 
 For index codec considerations, see [Index codecs]({{site.url}}{{site.baseurl}}/im-plugin/index-codecs/#snapshots).
+
+## Related articles
+
+- [Snapshot APIs]({{site.url}}{{site.baseurl}}/api-reference/snapshots/)
