[DOCS] Adding get snapshot API docs (#59098)

* Adding page for get snapshot API. * Adding values for state and cleaning up some other formatting. * Adding missing forward slash to GET request. * Updating values for start_time and end_time in TESTRESPONSE. * Swap "return" for "retrieve" * Swap "return" for "retrieve" 2 * Change .snapshot to .response * Adding response parameters and incorporating edits from review. * Update response example to include repository info * Change dash to underscore * Add data type for snapshot in response * Incorporating review comments and adding missing response definitions. * Minor rewording in description.
elastic · Jul 8, 2020 · b2beb9c · b2beb9c
1 parent 7bd93de
commit b2beb9c
Show file tree

Hide file tree

Showing 3 changed files with 246 additions and 10 deletions.
diff --git a/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc b/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc
@@ -0,0 +1,240 @@
+[[get-snapshot-api]]
+=== Get snapshot API
+++++
+<titleabbrev>Get snapshot</titleabbrev>
+++++
+
+Retrieves information about one or more snapshots.
+
+////
+[source,console]
+----
+PUT /_snapshot/my_repository
+{
+  "type": "fs",
+  "settings": {
+    "location": "my_backup_location"
+  }
+}
+
+PUT /_snapshot/my_repository/my_snapshot?wait_for_completion=true
+
+PUT /_snapshot/my_repository/snapshot_2?wait_for_completion=true
+----
+// TESTSETUP
+////
+
+[source,console]
+----
+GET /_snapshot/my_repository/my_snapshot
+----
+
+[[get-snapshot-api-request]]
+==== {api-request-title}
+
+`GET /_snapshot/<repository>/<snapshot>`
+
+[[get-snapshot-api-desc]]
+==== {api-description-title}
+
+Use the get snapshot API to return information about one or more snapshots, including:
+
+* Start and end time values
+* Version of {es} that created the snapshot
+* List of included indices
+* Current state of the snapshot
+* List of failures that occurred during the snapshot
+
+[[get-snapshot-api-path-params]]
+==== {api-path-parms-title}
+
+`<repository>`::
+(Required, string)
+Comma-separated list of snapshot repository names used to limit the request.
+Wildcard (`*`) expressions are supported.
++
+To get information about all snapshot repositories registered in the
+cluster, omit this parameter or use `*` or `_all`.
+
+`<snapshot>`::
+(Required, string)
+Comma-separated list of snapshot names to retrieve. Also accepts wildcards (`*`).
++
+* To get information about all snapshots in a registered repository, use a wildcard (`*`) or `_all`.
+* To get information about any snapshots that are currently running, use `_current`.
++
+NOTE: Using `_all` in a request fails if any snapshots are unavailable.
+Set <<get-snapshot-api-ignore-unavailable,`ignore_unavailable`>> to `true` to return only available snapshots.
+
+[role="child_attributes"]
+[[get-snapshot-api-request-body]]
+==== {api-request-body-title}
+
+[[get-snapshot-api-ignore-unavailable]]
+`ignore_unavailable`::
+(Optional, boolean)
+If `false`, the request returns an error for any snapshots that are unavailable. Defaults to `false`.
++
+If `true`, the request ignores snapshots that are unavailable, such as those that are corrupted or temporarily cannot be returned.
+
+`verbose`::
+(Optional, boolean)
+If `true`, returns all available information about a snapshot. Defaults to `true`.
++
+If `false`, omits additional information about the snapshot, such as version information, start and end times, and the number of snapshotted shards.
+
+[role="child_attributes"]
+[[get-snapshot-api-response-body]]
+==== {api-response-body-title}
+
+`snapshot`::
+(string)
+Name of the snapshot.
+
+`uuid`::
+(string)
+Universally unique identifier (UUID) of the snapshot.
+
+`version_id`::
+(int)
+Build ID of the {es} version used to create the snapshot.
+
+`version`::
+(float)
+{es} version used to create the snapshot.
+
+`indices`::
+(array)
+List of indices included in the snapshot.
+
+`data_streams`::
+(array)
+List of <<data-streams,data streams>> included in the snapshot.
+
+`include_global_state`::
+(boolean)
+Indicates whether the current cluster state is included in the snapshot.
+
+`start_time`::
+(string)
+Date timestamp of when the snapshot creation process started.
+
+`start_time_in_millis`::
+(long)
+The time, in milliseconds, when the snapshot creation process started.
+
+`end_time`::
+(string)
+Date timestamp of when the snapshot creation process ended.
+
+`end_time_in_millis`::
+(long)
+The time, in milliseconds, when the snapshot creation process ended.
+
+`duration_in_millis`::
+(long)
+How long, in milliseconds, it took to create the snapshot.
+
+[[get-snapshot-api-response-failures]]
+`failures`::
+(array)
+Lists any failures that occurred when creating the snapshot.
+
+`shards`::
+(object)
+Contains a count of shards in the snapshot.
++
+.Properties of `shards`
+[%collapsible%open]
+====
+`total`::
+(integer)
+Total number of shards included in the snapshot.
+
+`successful`::
+(integer)
+Number of shards that were successfully included in the snapshot.
+
+`failed`::
+(integer)
+Number of shards that failed to be included in the snapshot.
+====
+
+`state`::
++
+--
+(string)
+The snapshot `state` can be one of the following values:
+
+.Values for `state`
+[%collapsible%open]
+====
+`IN_PROGRESS`::
+  The snapshot is currently running.
+
+`SUCCESS`::
+  The snapshot finished and all shards were stored successfully.
+
+`FAILED`::
+  The snapshot finished with an error and failed to store any data.
+
+`PARTIAL`::
+  The global cluster state was stored, but data of at least one shard was not stored successfully.
+  The <<get-snapshot-api-response-failures,`failures`>> section of the response contains more detailed information about shards
+  that were not processed correctly.
+====
+--
+
+[[get-snapshot-api-example]]
+==== {api-examples-title}
+
+The following request returns information for `snapshot_2` in the `my_repository` repository.
+
+[source,console]
+----
+GET /_snapshot/my_repository/snapshot_2
+----
+
+The API returns the following response:
+
+[source,console-result]
+----
+{
+  "responses": [
+    {
+      "repository": "my_repository",
+      "snapshots": [
+        {
+          "snapshot": "snapshot_2",
+          "uuid": "vdRctLCxSketdKb54xw67g",
+          "version_id": <version_id>,
+          "version": <version>,
+          "indices": [],
+          "data_streams": [],
+          "include_global_state": true,
+          "state": "SUCCESS",
+          "start_time": "2020-07-06T21:55:18.129Z",
+          "start_time_in_millis": 1593093628850,
+          "end_time": "2020-07-06T21:55:18.129Z",
+          "end_time_in_millis": 1593094752018,
+          "duration_in_millis": 0,
+          "failures": [],
+          "shards": {
+            "total": 0,
+            "failed": 0,
+            "successful": 0
+          }
+        }
+      ]
+    }
+  ]
+}
+----
+// TESTRESPONSE[s/"uuid": "vdRctLCxSketdKb54xw67g"/"uuid": $body.responses.0.snapshots.0.uuid/]
+// TESTRESPONSE[s/"version_id": <version_id>/"version_id": $body.responses.0.snapshots.0.version_id/]
+// TESTRESPONSE[s/"version": <version>/"version": $body.responses.0.snapshots.0.version/]
+// TESTRESPONSE[s/"start_time": "2020-07-06T21:55:18.129Z"/"start_time": $body.responses.0.snapshots.0.start_time/]
+// TESTRESPONSE[s/"start_time_in_millis": 1593093628850/"start_time_in_millis": $body.responses.0.snapshots.0.start_time_in_millis/]
+// TESTRESPONSE[s/"end_time": "2020-07-06T21:55:18.129Z"/"end_time": $body.responses.0.snapshots.0.end_time/]
+// TESTRESPONSE[s/"end_time_in_millis": 1593094752018/"end_time_in_millis": $body.responses.0.snapshots.0.end_time_in_millis/]
+// TESTRESPONSE[s/"duration_in_millis": 0/"duration_in_millis": $body.responses.0.snapshots.0.duration_in_millis/]
diff --git a/docs/reference/snapshot-restore/apis/snapshot-restore-apis.asciidoc b/docs/reference/snapshot-restore/apis/snapshot-restore-apis.asciidoc
@@ -25,6 +25,7 @@ content may not be included yet.
 [[snapshot-management-apis]]
 === Snapshot management APIs
 * <<create-snapshot-api,Create snapshot>>
+* <<get-snapshot-api,Get snapshot>>
 * <<delete-snapshot-api,Delete snapshot>>
 
 include::put-repo-api.asciidoc[]
@@ -33,4 +34,5 @@ include::get-repo-api.asciidoc[]
 include::delete-repo-api.asciidoc[]
 include::clean-up-repo-api.asciidoc[]
 include::create-snapshot-api.asciidoc[]
+include::get-snapshot-api.asciidoc[]
 include::delete-snapshot-api.asciidoc[]
diff --git a/docs/reference/snapshot-restore/take-snapshot.asciidoc b/docs/reference/snapshot-restore/take-snapshot.asciidoc
@@ -112,30 +112,24 @@ snapshot and the list of failures that occurred during the snapshot. The snapsho
 
 [horizontal]
 `IN_PROGRESS`::
-
   The snapshot is currently running.
 
 `SUCCESS`::
-
   The snapshot finished and all shards were stored successfully.
 
 `FAILED`::
-
   The snapshot finished with an error and failed to store any data.
 
 `PARTIAL`::
-
-  The global cluster state was stored, but data of at least one shard wasn't stored successfully.
-  The `failure` section in this case should contain more detailed information about shards
+  The global cluster state was stored, but data of at least one shard was not stored successfully.
+  The `failures` section of the response contains more detailed information about shards
   that were not processed correctly.
 
 `INCOMPATIBLE`::
-
-  The snapshot was created with an old version of Elasticsearch and therefore is incompatible with
+  The snapshot was created with an old version of {es} and is incompatible with
   the current version of the cluster.
 
-
-Similar as for repositories, information about multiple snapshots can be queried in one go, supporting wildcards as well:
+Similar as for repositories, information about multiple snapshots can be queried in a single request, supporting wildcards as well:
 
 [source,console]
 -----------------------------------