From 755442058140bc064c6f6be059e39d1392b20a79 Mon Sep 17 00:00:00 2001
From: Tanguy Leroux <tlrx.dev@gmail.com>
Date: Mon, 1 Jul 2019 15:19:44 +0200
Subject: [PATCH] Update docs for Open/Close API (#43809)

Relates #43530
---
 docs/reference/indices/open-close.asciidoc | 66 ++++++++++++++++++----
 1 file changed, 56 insertions(+), 10 deletions(-)

diff --git a/docs/reference/indices/open-close.asciidoc b/docs/reference/indices/open-close.asciidoc
index 6d0866d303b..4ba434ecbbb 100644
--- a/docs/reference/indices/open-close.asciidoc
+++ b/docs/reference/indices/open-close.asciidoc
@@ -2,23 +2,69 @@
 == Open / Close Index API
 
 The open and close index APIs allow to close an index, and later on
-opening it. A closed index has almost no overhead on the cluster (except
-for maintaining its metadata), and is blocked for read/write operations.
-A closed index can be opened which will then go through the normal
-recovery process.
+opening it.
 
-The REST endpoint is `/{index}/_close` and `/{index}/_open`. For
-example:
+A closed index is blocked for read/write operations and does not allow
+all operations that opened indices allow. It is not possible to index
+documents or to search for documents in a closed index. This allows
+closed indices to not have to maintain internal data structures for
+indexing or searching documents, resulting in a smaller overhead on
+the cluster.
+
+When opening or closing an index, the master is responsible for
+restarting the index shards to reflect the new state of the index.
+The shards will then go through the normal recovery process. The
+data of opened/closed indices is automatically replicated by the
+cluster to ensure that enough shard copies are safely kept around
+at all times.
+
+The REST endpoint is `/{index}/_close` and `/{index}/_open`.
+
+The following example shows how to close an index:
 
 [source,js]
 --------------------------------------------------
 POST /my_index/_close
-
-POST /my_index/_open
 --------------------------------------------------
 // CONSOLE
 // TEST[s/^/PUT my_index\n/]
 
+This will return the following response:
+
+[source,js]
+--------------------------------------------------
+{
+    "acknowledged" : true,
+    "shards_acknowledged" : true,
+    "indices" : {
+        "my_index" : {
+            "closed" : true
+        }
+    }
+}
+--------------------------------------------------
+// TESTRESPONSE
+
+A closed index can be reopened like this:
+
+[source,js]
+--------------------------------------------------
+POST /my_index/_open
+--------------------------------------------------
+// CONSOLE
+// TEST[s/^/PUT my_index\nPOST my_index\/_close\n/]
+
+which will yield the following response:
+
+[source,js]
+--------------------------------------------------
+{
+    "acknowledged" : true,
+    "shards_acknowledged" : true
+}
+--------------------------------------------------
+// TESTRESPONSE
+
 It is possible to open and close multiple indices. An error will be thrown
 if the request explicitly refers to a missing index. This behaviour can be
 disabled using the `ignore_unavailable=true` parameter.
@@ -36,6 +82,6 @@ API by setting `cluster.indices.close.enable` to `false`. The default is `true`.
 [float]
 === Wait For Active Shards
 
-Because opening an index allocates its shards, the
+Because opening or closing an index allocates its shards, the
 <<create-index-wait-for-active-shards,`wait_for_active_shards`>> setting on
-index creation applies to the index opening action as well.
+index creation applies to the `_open` and `_close` index actions as well.