[DOCS] Reformats search template and multi search template APIs (#46236)

* [DOCS] Reformats search template and multi search template APIs.
Co-Authored-By: James Rodewig <[email protected]>

Author: szabosteve

docs/reference/search/search-template.asciidoc

@@ -1,8 +1,7 @@
 [[search-template]]
 === Search Template
 
-The `/_search/template` endpoint allows to use the mustache language to pre render search requests,
-before they are executed and fill existing templates with template parameters.
+Allows you to use the mustache language to pre render search requests.
 
 [source,js]
 ------------------------------------------
@@ -22,19 +21,87 @@ GET _search/template
 // CONSOLE
 // TEST[setup:twitter]
 
+[[search-template-api-request]]
+==== {api-request-title}
+
+`GET _search/template`
+
+
+[[search-template-api-desc]]
+==== {api-description-title}
+
+The `/_search/template` endpoint allows you to use the mustache language to pre- 
+render search requests, before they are executed and fill existing templates 
+with template parameters.
+
 For more information on how Mustache templating and what kind of templating you
 can do with it check out the http://mustache.github.io/mustache.5.html[online
 documentation of the mustache project].
 
-NOTE: The mustache language is implemented in Elasticsearch as a sandboxed
-scripting language, hence it obeys settings that may be used to enable or
-disable scripts per type and context as described in the
-<<allowed-script-types-setting, scripting docs>>
+NOTE: The mustache language is implemented in {es} as a sandboxed scripting 
+language, hence it obeys settings that may be used to enable or disable scripts 
+per type and context as described in the 
+<<allowed-script-types-setting, scripting docs>>.
+
+
+[[search-template-api-path-params]]
+==== {api-path-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
+
+
+[[search-template-api-query-params]]
+==== {api-query-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
+
+`ccs_minimize_roundtrips`::
+  (Optional, boolean) If `true`, network round-trips are minimized for 
+ cross-cluster search requests. Defaults to `true`.
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
+
+`explain`::
+  (Optional, boolean) If `true`, the response includes additional details about 
+  score computation as part of a hit. Defaults to `false`.
+
+`ignore_throttled`::
+  (Optional, boolean) If `true`, specified concrete, expanded or aliased indices 
+  are not included in the response when throttled. Defaults to `false`. 
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=preference]
+
+`profile`::
+  (Optional, boolean) If `true`, the query execution is profiled. Defaults 
+  to `false`.
+
+`rest_total_hits_as_int`::
+  (Optional, boolean) If `true`, `hits.total` are rendered as an integer in 
+  the response. Defaults to `false`.
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=routing]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=scroll]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=search_type]
+
+`typed_keys`::
+  (Optional, boolean) If `true`, aggregation and suggester names are 
+  prefixed by their respective types in the response. Defaults to `false`.
+  
+
+[[search-template-api-request-body]]
+==== {api-request-body-title}
+
+The API request body must contain the search definition template and its parameters.
+
+
+[[search-template-api-example]]
+==== {api-response-codes-title}
 
-[float]
-==== Examples
 
-[float]
 [[pre-registered-templates]]
 ===== Store a search template
 
@@ -61,8 +128,8 @@ POST _scripts/<templateid>
 
 //////////////////////////
 
-We want to be sure that the template has been created,
-because we'll use it later.
+The API returns the following result if the template has been successfully 
+created:
 
 [source,js]
 --------------------------------------------------
@@ -74,7 +141,8 @@ because we'll use it later.
 
 //////////////////////////
 
-This template can be retrieved by
+
+The template can be retrieved by calling
 
 [source,js]
 ------------------------------------------
@@ -83,7 +151,7 @@ GET _scripts/<templateid>
 // CONSOLE
 // TEST[continued]
 
-which is rendered as:
+The API returns the following result:
 
 [source,js]
 ------------------------------------------
@@ -101,7 +169,8 @@ which is rendered as:
 ------------------------------------------
 // TESTRESPONSE
 
-This template can be deleted by
+
+This template can be deleted by calling
 
 [source,js]
 ------------------------------------------
@@ -110,26 +179,12 @@ DELETE _scripts/<templateid>
 // CONSOLE
 // TEST[continued]
 
-//////////////////////////
-
-We want to be sure that the template has been created,
-because we'll use it later.
-
-[source,js]
---------------------------------------------------
-{
-    "acknowledged" : true
-}
---------------------------------------------------
-// TESTRESPONSE
 
-//////////////////////////
 
-[float]
 [[use-registered-templates]]
-===== Use a stored search template
+===== Using a stored search template
 
-To use a stored template at search time use:
+To use a stored template at search time send the following request:
 
 [source,js]
 ------------------------------------------
@@ -145,11 +200,12 @@ GET _search/template
 // TEST[catch:missing]
 <1> Name of the stored template script.
 
-[float]
+
 [[_validating_templates]]
-==== Validate a search template
+==== Validating a search template
 
-A template can be rendered in a response with given parameters using
+A template can be rendered in a response with given parameters by using the 
+following request:
 
 [source,js]
 ------------------------------------------
@@ -165,7 +221,8 @@ GET _render/template
 ------------------------------------------
 // CONSOLE
 
-This call will return the rendered template:
+
+The API returns the rendered template:
 
 [source,js]
 ------------------------------------------
@@ -185,7 +242,8 @@ This call will return the rendered template:
 // TESTRESPONSE
 <1> `status` array has been populated with values from the `params` object.
 
-Stored templates can also be rendered using
+
+Stored templates can also be rendered by calling the following request:
 
 [source,js]
 ------------------------------------------
@@ -198,10 +256,10 @@ GET _render/template/<template_name>
 ------------------------------------------
 // NOTCONSOLE
 
-[float]
-===== Explain
+[[search-template-explain-parameter]]
+===== Using the explain parameter
 
-You can use `explain` parameter when running a template:
+You can use the `explain` parameter when running a template:
 
 [source,js]
 ------------------------------------------
@@ -217,10 +275,11 @@ GET _search/template
 // CONSOLE
 // TEST[catch:missing]
 
-[float]
+
+[[search-template-profile-parameter]]
 ===== Profiling
 
-You can use `profile` parameter when running a template:
+You can use the `profile` parameter when running a template:
 
 [source,js]
 ------------------------------------------
@@ -236,7 +295,8 @@ GET _search/template
 // CONSOLE
 // TEST[catch:missing]
 
-[float]
+
+[[search-template-query-string-single]]
 ===== Filling in a query string with a single value
 
 [source,js]
@@ -258,7 +318,7 @@ GET _search/template
 // CONSOLE
 // TEST[setup:twitter]
 
-[float]
+[[search-template-converting-to-json]]
 ===== Converting parameters to JSON
 
 The `{{#toJson}}parameter{{/toJson}}` function can be used to convert parameters
@@ -337,7 +397,7 @@ which is rendered as:
 ------------------------------------------
 // NOTCONSOLE
 
-[float]
+[[search-template-concatenate-array]]
 ===== Concatenating array of values
 
 The `{{#join}}array{{/join}}` function can be used to concatenate the
@@ -422,7 +482,7 @@ which is rendered as:
 ------------------------------------------
 // NOTCONSOLE
 
-[float]
+[[search-template-default-values]]
 ===== Default values
 
 A default value is written as `{{var}}{{^var}}default{{/var}}` for instance:
@@ -476,7 +536,7 @@ for `end`:
 ------------------------------------------
 // NOTCONSOLE
 
-[float]
+[[search-template-conditional-clauses]]
 ===== Conditional clauses
 
 Conditional clauses cannot be expressed using the JSON form of the template.
@@ -485,6 +545,7 @@ we wanted to run a `match` query on the `line` field, and optionally wanted
 to filter by line numbers, where `start` and `end` are optional.
 
 The `params` would look like:
+
 [source,js]
 ------------------------------------------
 {
@@ -500,6 +561,7 @@ The `params` would look like:
 // NOTCONSOLE
 <1> All three of these elements are optional.
 
+
 We could write the query as:
 
 [source,js]
@@ -556,11 +618,12 @@ via the REST API, should be written as a string:
 ==================================
 
 
-[float]
+[[search-template-encode-urls]]
 ===== Encoding URLs
 
 The `{{#url}}value{{/url}}` function can be used to encode a string value
-in a HTML encoding form as defined in by the http://www.w3.org/TR/html4/[HTML specification].
+in a HTML encoding form as defined in by the 
+http://www.w3.org/TR/html4/[HTML specification].
 
 As an example, it is useful to encode a URL:
 
@@ -583,6 +646,7 @@ GET _render/template
 ------------------------------------------
 // CONSOLE
 
+
 The previous query will be rendered as:
 
 [source,js]
@@ -602,8 +666,19 @@ The previous query will be rendered as:
 [[multi-search-template]]
 === Multi Search Template
 
-The multi search template API allows to execute several search template
-requests within the same API using the `_msearch/template` endpoint.
+Allows to execute several search template requests.
+
+[[multi-search-template-api-request]]
+==== {api-request-title}
+
+`GET _msearch/template`
+
+
+[[multi-search-template-api-desc]]
+==== {api-description-title}
+
+Allows to execute several search template requests within the same API using the 
+`_msearch/template` endpoint.
 
 The format of the request is similar to the <<search-multi-search, Multi
 Search API>> format:
@@ -617,11 +692,15 @@ body\n
 --------------------------------------------------
 // NOTCONSOLE
 
-The header part supports the same `index`, `search_type`,
-`preference`, and `routing` options as the usual Multi Search API.
+The header part supports the same `index`, `search_type`, `preference`, and 
+`routing` options as the Multi Search API.
+
+The body includes a search template body request and supports inline, stored and 
+file templates.
+
 
-The body includes a search template body request and supports inline,
-stored and file templates. Here is an example:
+[[multi-search-template-api-example]]
+==== {api-examples-title}
 
 [source,js]
 --------------------------------------------------
@@ -643,5 +722,5 @@ $ curl -H "Content-Type: application/x-ndjson" -XGET localhost:9200/_msearch/tem
 The response returns a `responses` array, which includes the search template
 response for each search template request matching its order in the original
 multi search template request. If there was a complete failure for that specific
-search template request, an object with `error` message will be returned in place
-of the actual search response.
+search template request, an object with `error` message will be returned in 
+place of the actual search response.