From 0b4fb05540cb32fa2ed3099ed05b2b26a4257379 Mon Sep 17 00:00:00 2001
From: James Rodewig <james.rodewig@elastic.co>
Date: Fri, 4 Oct 2019 13:50:09 -0400
Subject: [PATCH] [DOCS] Reformat refresh API docs (#46667) (#47589)

---
 docs/reference/how-to/indexing-speed.asciidoc |   5 +-
 docs/reference/index-modules.asciidoc         |   1 +
 docs/reference/indices/refresh.asciidoc       | 105 +++++++++++++++---
 3 files changed, 93 insertions(+), 18 deletions(-)

diff --git a/docs/reference/how-to/indexing-speed.asciidoc b/docs/reference/how-to/indexing-speed.asciidoc
index f4c224829a456..52d5d04699d1f 100644
--- a/docs/reference/how-to/indexing-speed.asciidoc
+++ b/docs/reference/how-to/indexing-speed.asciidoc
@@ -43,8 +43,7 @@ The operation that consists of making changes visible to search - called a
 <<indices-refresh,refresh>> - is costly, and calling it often while there is
 ongoing indexing activity can hurt indexing speed.
 
-By default, Elasticsearch runs this operation every second, but only on
-indices that have received one search request or more in the last 30 seconds.
+include::{docdir}/indices/refresh.asciidoc[tag=refresh-interval-default]
 This is the optimal configuration if you have no or very little search traffic
 (e.g. less than one search request every 5 minutes) and want to optimize for
 indexing speed. This behavior aims to automatically optimize bulk indexing in
@@ -55,7 +54,7 @@ On the other hand, if your index experiences regular search requests, this
 default behavior means that Elasticsearch will refresh your index every 1
 second. If you can afford to increase the amount of time between when a document
 gets indexed and when it becomes visible, increasing the
-<<dynamic-index-settings,`index.refresh_interval`>> to a larger value, e.g.
+<<index-refresh-interval-setting,`index.refresh_interval`>> to a larger value, e.g.
 `30s`, might help improve indexing speed.
 
 [float]
diff --git a/docs/reference/index-modules.asciidoc b/docs/reference/index-modules.asciidoc
index 9ae1dac826e3f..11babf3e58afe 100644
--- a/docs/reference/index-modules.asciidoc
+++ b/docs/reference/index-modules.asciidoc
@@ -106,6 +106,7 @@ specific index module:
     How long a shard can not receive a search or get request until it's considered
     search idle. (default is `30s`)
 
+[[index-refresh-interval-setting]]
 `index.refresh_interval`::
 
     How often to perform a refresh operation, which makes recent changes to the
diff --git a/docs/reference/indices/refresh.asciidoc b/docs/reference/indices/refresh.asciidoc
index bba4ec5c9a5d7..a6a8b1d6ef18d 100644
--- a/docs/reference/indices/refresh.asciidoc
+++ b/docs/reference/indices/refresh.asciidoc
@@ -1,28 +1,103 @@
 [[indices-refresh]]
-=== Refresh
+=== Refresh API
+++++
+<titleabbrev>Refresh</titleabbrev>
+++++
 
-The refresh API allows to explicitly refresh one or more index, making
-all operations performed since the last refresh available for search.
-The (near) real-time capabilities depend on the index engine used. For
-example, the internal one requires refresh to be called, but by default a
-refresh is scheduled periodically.
+Refreshes one or more indices.
 
 [source,console]
---------------------------------------------------
+----
 POST /twitter/_refresh
---------------------------------------------------
+----
 // TEST[setup:twitter]
 
-[float]
-==== Multi Index
 
-The refresh API can be applied to more than one index with a single
-call, or even on `_all` the indices.
+[[refresh-api-request]]
+==== {api-request-title}
+
+`POST <index>/_refresh`
+
+`GET <index>/_refresh`
+
+`POST /_refresh`
+
+`GET /_refresh`
+
+
+[[refresh-api-desc]]
+==== {api-description-title}
+
+Use the refresh API to explicitly refresh one or more indices.
+A _refresh_ makes all operations performed on an index
+since the last refresh
+available for search.
+
+// tag::refresh-interval-default[]
+By default, Elasticsearch periodically refreshes indices every second, but only on
+indices that have received one search request or more in the last 30 seconds.
+// end::refresh-interval-default[]
+You can change this default interval
+using the <<index-refresh-interval-setting,`index.refresh_interval`>> setting.
+
+[IMPORTANT]
+====
+Refreshes are a resource-intensive.
+To ensure good cluster performance,
+we recommend waiting for {es}'s periodic refresh 
+rather than performing an explicit refresh
+when possible.
+
+If your application workflow
+indexes documents and then runs a search
+to retrieve the indexed document,
+we recommend using the <<docs-index_,index API>>'s
+`refresh=wait_for` query parameter option.
+This option ensures the indexing operation waits
+for a periodic refresh
+before running the search.
+====
+
+[[refresh-api-path-params]]
+==== {api-path-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
++
+To refresh all indices in the cluster,
+omit this parameter
+or use a value of `_all` or `*`.
+
+
+[[refresh-api-query-params]]
+==== {api-query-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
++
+Defaults to `open`.
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
+
+
+[[refresh-api-example]]
+==== {api-examples-title}
+
+
+[[refresh-api-multiple-ex]]
+===== Refresh several indices
 
 [source,console]
---------------------------------------------------
+----
 POST /kimchy,elasticsearch/_refresh
+----
+// TEST[s/^/PUT kimchy\nPUT elasticsearch\n/]
+
 
+[[refresh-api-all-ex]]
+===== Refresh all indices
+
+[source,console]
+----
 POST /_refresh
---------------------------------------------------
-// TEST[s/^/PUT kimchy\nPUT elasticsearch\n/]
+----