Add basic documentation for Searchable Snapshots REST APIs

docs/reference/rest-api/index.asciidoc

@@ -28,6 +28,7 @@ not be included yet.
 * <<indices-reload-analyzers,Reload Search Analyzers API>>
 * <<rollup-apis,Rollup APIs>>
 * <<search, Search APIs>>
+* <<searchable-snapshots-apis, Searchable snapshots APIs>>
 * <<security-api,Security APIs>>
 * <<snapshot-lifecycle-management-api,Snapshot lifecycle management APIs>>
 * <<transform-apis,{transform-cap} APIs>>
@@ -54,6 +55,7 @@ include::{es-repo-dir}/migration/migration.asciidoc[]
 include::{es-repo-dir}/indices/apis/reload-analyzers.asciidoc[]
 include::{es-repo-dir}/rollup/rollup-api.asciidoc[]
 include::{es-repo-dir}/search.asciidoc[]
+include::{es-repo-dir}/searchable-snapshots/apis/searchable-snapshots-apis.asciidoc[]
 include::{xes-repo-dir}/rest-api/security.asciidoc[]
 include::{es-repo-dir}/slm/apis/slm-api.asciidoc[]
 include::{es-repo-dir}/transform/apis/index.asciidoc[]

docs/reference/searchable-snapshots/apis/clear-cache.asciidoc

@@ -0,0 +1,76 @@
+[role="xpack"]
+[testenv="basic"]
+[[searchable-snapshots-api-clear-cache]]
+=== Clear cache API
+++++
+<titleabbrev>Clear cache</titleabbrev>
+++++
+
+experimental[]
+
+Clear the cache of searchable snapshots.
+
+[[searchable-snapshots-api-clear-cache-request]]
+==== {api-request-title}
+
+`POST /_searchable_snapshots/cache/clear`
+
+`POST /<index>/_searchable_snapshots/cache/clear`
+
+[[searchable-snapshots-api-clear-cache-prereqs]]
+==== {api-prereq-title}
+
+If the {es} {security-features} are enabled, you must have the
+`manage` cluster privilege and the `manage` index privilege
+for any included indices to use this API.
+For more information, see <<security-privileges>>.
+
+[[searchable-snapshots-api-clear-cache-desc]]
+==== {api-description-title}
+
+
+[[searchable-snapshots-api-clear-cache-path-params]]
+==== {api-path-parms-title}
+
+`<index>`::
+(Optional, string)
+A comma-separated list of index names for which the
+searchable snapshots cache must be cleared.
+
+
+[[searchable-snapshots-api-clear-cache-example]]
+==== {api-examples-title}
+////
+[source,console]
+-----------------------------------
+PUT /docs
+{
+    "settings" : {
+        "index.number_of_shards" : 1,
+        "index.number_of_replicas" : 0
+    }
+}
+
+PUT /_snapshot/my_repository/my_snapshot?wait_for_completion=true
+{
+    "include_global_state": false,
+    "indices": "docs"
+}
+
+DELETE /docs
+
+POST /_snapshot/my_repository/my_snapshot/_mount?wait_for_completion=true
+{
+  "index": "docs"
+}
+-----------------------------------
+// TEST[setup:setup-repository]
+////
+
+Clears the cache of the index `docs`:
+
+[source,console]
+--------------------------------------------------
+POST /docs/_searchable_snapshots/cache/clear
+--------------------------------------------------
+// TEST[continued]

docs/reference/searchable-snapshots/apis/get-stats.asciidoc

@@ -0,0 +1,76 @@
+[role="xpack"]
+[testenv="basic"]
+[[searchable-snapshots-api-stats]]
+=== Searchable snapshot statistics API
+++++
+<titleabbrev>Searchable snapshot statistics</titleabbrev>
+++++
+
+experimental[]
+
+Retrieve various statistics about searchable snapshots.
+
+[[searchable-snapshots-api-stats-request]]
+==== {api-request-title}
+
+`GET /_searchable_snapshots/stats`
+
+`GET /<index>/_searchable_snapshots/stats`
+
+[[searchable-snapshots-api-stats-prereqs]]
+==== {api-prereq-title}
+
+If the {es} {security-features} are enabled, you must have the
+`manage` cluster privilege and the `manage` index privilege
+for any included indices to use this API.
+For more information, see <<security-privileges>>.
+
+[[searchable-snapshots-api-stats-desc]]
+==== {api-description-title}
+
+
+[[searchable-snapshots-api-stats-path-params]]
+==== {api-path-parms-title}
+
+`<index>`::
+(Optional, string)
+A comma-separated list of index names for which the
+statistics must be retrieved.
+
+
+[[searchable-snapshots-api-stats-example]]
+==== {api-examples-title}
+////
+[source,console]
+-----------------------------------
+PUT /docs
+{
+    "settings" : {
+        "index.number_of_shards" : 1,
+        "index.number_of_replicas" : 0
+    }
+}
+
+PUT /_snapshot/my_repository/my_snapshot?wait_for_completion=true
+{
+    "include_global_state": false,
+    "indices": "docs"
+}
+
+DELETE /docs
+
+POST /_snapshot/my_repository/my_snapshot/_mount?wait_for_completion=true
+{
+  "index": "docs"
+}
+-----------------------------------
+// TEST[setup:setup-repository]
+////
+
+Retrieves the statistics of the index `docs`:
+
+[source,console]
+--------------------------------------------------
+GET /docs/_searchable_snapshots/stats
+--------------------------------------------------
+// TEST[continued]

docs/reference/searchable-snapshots/apis/mount-snapshot.asciidoc

@@ -0,0 +1,126 @@
+[role="xpack"]
+[testenv="basic"]
+[[searchable-snapshots-api-mount-snapshot]]
+=== Mount snapshot API
+++++
+<titleabbrev>Mount snapshot</titleabbrev>
+++++
+
+experimental[]
+
+Mount a snapshot as a searchable index.
+
+[[searchable-snapshots-api-mount-request]]
+==== {api-request-title}
+
+`POST /_snapshot/<repository>/<snapshot>/_mount`
+
+[[searchable-snapshots-api-mount-prereqs]]
+==== {api-prereq-title}
+
+If the {es} {security-features} are enabled, you must have the
+`manage` cluster privilege and the `manage` index privilege
+for any included indices to use this API.
+For more information, see <<security-privileges>>.
+
+[[searchable-snapshots-api-mount-desc]]
+==== {api-description-title}
+
+
+[[searchable-snapshots-api-mount-path-params]]
+==== {api-path-parms-title}
+
+`<repository>`::
+(Required, string)
+The name of the repository containing
+the snapshot of the index to mount.
+
+`<snapshot>`::
+(Required, string)
+The name of the snapshot of the index
+to mount.
+
+[[searchable-snapshots-api-mount-query-params]]
+==== {api-query-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=wait_for_completion]
+
+[[searchable-snapshots-api-mount-request-body]]
+==== {api-request-body-title}
+
+`index`::
+(Required, string)
+Name of the index contained in the snapshot
+whose data is to be mounted.
+
+If no `renamed_index` is specified this name
+will also be used to create the new index.
+
+`renamed_index`::
++
+--
+(Optional, string)
+Name of the index that will be created.
+--
+
+`index_settings`::
++
+--
+(Optional, object)
+Settings that should be added to the index when it is mounted.
+--
+
+`ignore_index_settings`::
++
+--
+(Optional, array of strings)
+Names of settings that should be removed from the index when it is mounted.
+--
+
+[[searchable-snapshots-api-mount-example]]
+==== {api-examples-title}
+////
+[source,console]
+-----------------------------------
+PUT /my_docs
+{
+    "settings" : {
+        "index.number_of_shards" : 1,
+        "index.number_of_replicas" : 0
+    }
+}
+
+PUT /_snapshot/my_repository/my_snapshot?wait_for_completion=true
+{
+    "include_global_state": false,
+    "indices": "my_docs"
+}
+
+DELETE /my_docs
+-----------------------------------
+// TEST[setup:setup-repository]
+////
+
+Mounts the index `my_docs` from an existing snapshot named `my_snapshot` stored
+in the `my_repository` as a new index `docs`:
+
+[source,console]
+--------------------------------------------------
+POST /_snapshot/my_repository/my_snapshot/_mount?wait_for_completion=true
+{
+  "index": "my_docs", <1>
+  "renamed_index": "docs", <2>
+  "index_settings": { <3>
+    "index.number_of_replicas": 0
+  },
+  "ignored_index_settings": [ "index.refresh_interval" ] <4>
+}
+--------------------------------------------------
+// TEST[continued]
+
+<1> The name of the index in the snapshot to mount
+<2> The name of the index to create
+<3> Any index settings to add to the new index
+<4> List of indices to ignore when mounting the snapshotted index

docs/reference/searchable-snapshots/apis/searchable-snapshots-apis.asciidoc

@@ -0,0 +1,16 @@
+[role="xpack"]
+[testenv="basic"]
+[[searchable-snapshots-apis]]
+== Searchable snapshots APIs
+
+experimental[]
+
+You can use the following APIs to perform searchable snapshots operations.
+
+* <<searchable-snapshots-api-mount-snapshot,Mount snapshot>>
+* <<searchable-snapshots-api-clear-cache,Clear cache>>
+* <<searchable-snapshots-api-stats,Get stats>>
+
+include::mount-snapshot.asciidoc[]
+include::clear-cache.asciidoc[]
+include::get-stats.asciidoc[]

x-pack/plugin/src/test/resources/rest-api-spec/api/searchable_snapshots.clear_cache.json

@@ -1,7 +1,7 @@
 {
   "searchable_snapshots.clear_cache": {
     "documentation": {
-      "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/searchable-snapshots-clear-indices.html //NORELEASE This API should be documented. We expect this API to be stable at the time it is merged in master, but in case it is not its stability should be documented appropriately."
+      "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/searchable-snapshots-api-clear-cache.html"
     },
     "stability": "experimental",
     "url": {

x-pack/plugin/src/test/resources/rest-api-spec/api/searchable_snapshots.mount.json

@@ -1,7 +1,7 @@
 {
   "searchable_snapshots.mount": {
     "documentation": {
-      "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/searchable-snapshots-mount.html //NORELEASE This API should be documented. We expect this API to be stable at the time it is merged in master, but in case it is not its stability should be documented appropriately."
+      "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/searchable-snapshots-api-mount-snapshot"
     },
     "stability": "experimental",
     "url": {

x-pack/plugin/src/test/resources/rest-api-spec/api/searchable_snapshots.stats.json

@@ -1,7 +1,7 @@
 {
   "searchable_snapshots.stats": {
     "documentation": {
-      "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/searchable-snapshots-get-stats.html //NORELEASE This API should be documented. We expect this API to be stable at the time it is merged in master, but in case it is not its stability should be documented appropriately."
+      "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/searchable-snapshots-api-stats.html"
     },
     "stability": "experimental",
     "url": {