Reformats mget API (#47477)

* Reformats mget API

* Update docs/reference/docs/get.asciidoc

Co-Authored-By: James Rodewig <james.rodewig@elastic.co>

* Incorporated feedback.

docs/reference/docs/get.asciidoc

@@ -6,6 +6,12 @@
 
 Retrieves the specified JSON document from an index.
 
+[source,console]
+--------------------------------------------------
+GET twitter/_doc/0
+--------------------------------------------------
+// TEST[setup:twitter]
+
 [[docs-get-api-request]]
 ==== {api-request-title}
 
@@ -150,32 +156,21 @@ deleted documents in the background as you continue to index more data.
 [[docs-get-api-query-params]]
 ==== {api-query-parms-title}
 
-`preference`::
-(Optional, string) Specify the node or shard the operation should
-be performed on (default: random).
+include::{docdir}/rest-api/common-parms.asciidoc[tag=preference]
 
-`realtime`::
-(Optional, boolean) Set to `false` to disable real time GET
-(default: `true`). See <<realtime>>.
+include::{docdir}/rest-api/common-parms.asciidoc[tag=realtime]
 
 include::{docdir}/rest-api/common-parms.asciidoc[tag=refresh]
 
 include::{docdir}/rest-api/common-parms.asciidoc[tag=routing]
 
-`stored_fields`::
-(Optional, boolean) Set to `true` to retrieve the document fields stored in the
-index rather than the document `_source` (default: `false`).
+include::{docdir}/rest-api/common-parms.asciidoc[tag=stored_fields]
 
-`_source`::
-(Optional, list) Set to `false` to disable source retrieval (default: `true`).
- You can also specify a comma-separated list of the fields
-you want to retrieve.
+include::{docdir}/rest-api/common-parms.asciidoc[tag=source]
 
-`_source_excludes`::
-(Optional, list) Specify the source fields you want to exclude.
+include::{docdir}/rest-api/common-parms.asciidoc[tag=source_excludes]
 
-`_source_includes`::
-(Optional, list) Specify the source fields you want to retrieve.
+include::{docdir}/rest-api/common-parms.asciidoc[tag=source_includes]
 
 include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-version]
 

docs/reference/docs/multi-get.asciidoc

@@ -1,15 +1,10 @@
 [[docs-multi-get]]
-=== Multi Get API
+=== Multi get (mget) API
+++++
+<titleabbrev>Multi get</titleabbrev>
+++++
 
-The Multi get API returns multiple documents based on an index and id
-(and possibly routing). The response includes a `docs` array
-with all the fetched documents in order corresponding to the original multi-get
-request (if there was a failure for a specific get, an object containing this
-error is included in place in the response instead). The structure of a
-successful get is similar in structure to a document provided by the
-<<docs-get,get>> API.
-
-Here is an example:
+Retrieves multiple JSON documents by ID. 
 
 [source,console]
 --------------------------------------------------
@@ -17,23 +12,121 @@ GET /_mget
 {
     "docs" : [
         {
-            "_index" : "test",
+            "_index" : "twitter",
             "_id" : "1"
         },
         {
-            "_index" : "test",
+            "_index" : "twitter",
             "_id" : "2"
         }
     ]
 }
 --------------------------------------------------
+// TEST[setup:twitter]
+
+[[docs-multi-get-api-request]]
+==== {api-request-title}
+
+`GET /_mget`
+
+`GET /<index>/_mget`
+
+[[docs-multi-get-api-desc]]
+==== {api-description-title}
+
+You use `mget` to retrieve multiple documents from one or more indices.
+If you specify an index in the request URI, you only need to specify the document IDs in the request body.
+
+[[mget-security]]
+===== Security
+
+See <<url-access-control>>.
+
+[[multi-get-partial-responses]]
+===== Partial responses
+
+To ensure fast responses, the multi get API responds with partial results if one or more shards fail. 
+See <<shard-failures, Shard failures>> for more information.
+
+[[docs-multi-get-api-path-params]]
+==== {api-path-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
+
+[[docs-multi-get-api-query-params]]
+==== {api-query-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=preference]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=realtime]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=refresh]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=routing]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=stored_fields]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=source]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=source_excludes]
 
-The `mget` endpoint can also be used against an index (in which case it
-is not required in the body):
+include::{docdir}/rest-api/common-parms.asciidoc[tag=source_includes]
+
+[[docs-multi-get-api-request-body]]
+==== {api-request-body-title}
+
+`docs`::
+(Optional, array) The documents you want to retrieve.
+Required if no index is specified in the request URI.
+You can specify the following attributes for each
+document:
++
+--
+`_id`::
+(Required, string) The unique document ID.
+
+`_index`::
+(Optional, string)
+The index that contains the document.
+Required if no index is specified in the request URI.
+
+`_routing`::
+(Optional, string) The key for the primary shard the document resides on.
+Required if routing is used during indexing.
+
+`_source`::
+(Optional, boolean) If `false`,  excludes all `_source` fields. Defaults to `true`.
+`source_include`:::
+(Optional, array) The fields to extract and return from the `_source` field.
+`source_exclude`:::
+(Optional, array) The fields to exclude from the returned `_source` field.
+
+`_stored_fields`::
+(Optional, array) The stored fields you want to retrieve.
+--
+
+`ids`::
+(Optional, array) The IDs of the documents you want to retrieve.
+Allowed when the index is specified in the request URI.
+
+[[multi-get-api-response-body]]
+==== {api-response-body-title}
+
+The response includes a `docs` array that contains the documents in the order specified in the request. 
+The structure of the returned documents is similar to that returned by the <<docs-get,get>> API.
+If there is a failure getting a particular document, the error is included in place of the document. 
+
+[[docs-multi-get-api-example]]
+==== {api-examples-title}
+
+[[mget-ids]]
+===== Get documents by ID
+
+If you specify an index in the request URI, only the document IDs are required in the request body:
 
 [source,console]
 --------------------------------------------------
-GET /test/_mget
+GET /twitter/_mget
 {
     "docs" : [
         {
@@ -45,30 +138,31 @@ GET /test/_mget
     ]
 }
 --------------------------------------------------
-//CONSOLE
+// TEST[setup:twitter]
 
-In which case, the `ids` element can directly be used to simplify the
-request:
+You can use the `ids` element to simplify the request:
 
 [source,console]
 --------------------------------------------------
-GET /test/_mget
+GET /twitter/_mget
 {
     "ids" : ["1", "2"]
 }
 --------------------------------------------------
+// TEST[setup:twitter]
 
-[float]
 [[mget-source-filtering]]
-==== Source filtering
+===== Filter source fields
 
-By default, the `_source` field will be returned for every document (if stored).
-Similar to the <<get-source-filtering,get>> API, you can retrieve only parts of
-the `_source` (or not at all) by using the `_source` parameter. You can also use
-the url parameters `_source`, `_source_includes`, and `_source_excludes` to specify defaults,
-which will be used when there are no per-document instructions.
+By default, the `_source` field is returned for every document (if stored). 
+Use the `_source` and `_source_include` or `source_exclude` attributes to 
+filter what fields are returned for a particular document.
+You can include the `_source`, `_source_includes`, and `_source_excludes` query parameters in the
+request URI to specify the defaults to use when there are no per-document instructions.
 
-For example:
+For example, the following request sets `_source` to false for document 1 to exclude the
+source entirely, retrieves `field3` and `field4` from document 2, and retrieves the `user` field
+from document 3 but filters out the `user.location` field.
 
 [source,console]
 --------------------------------------------------
@@ -97,13 +191,16 @@ GET /_mget
 }
 --------------------------------------------------
 
-
-[float]
 [[mget-fields]]
-==== Fields
+===== Get stored fields
+
+Use the `stored_fields` attribute to specify the set of stored fields you want
+to retrieve. Any requested fields that are not stored are ignored. 
+You can include the `stored_fields` query parameter in the request URI to specify the defaults 
+to use when there are no per-document instructions. 
 
-Specific stored fields can be specified to be retrieved per document to get, similar to the <<get-stored-fields,stored_fields>> parameter of the Get API.
-For example:
+For example, the following request retrieves `field1` and `field2` from document 1, and
+`field3` and `field4`from document 2:
 
 [source,console]
 --------------------------------------------------
@@ -124,8 +221,9 @@ GET /_mget
 }
 --------------------------------------------------
 
-Alternatively, you can specify the `stored_fields` parameter in the query string
-as a default to be applied to all documents.
+The following request retrieves `field1` and `field2` from all documents by default.
+These default fields are returned for document 1, but 
+overridden to return `field3` and `field4` for document 2.
 
 [source,console]
 --------------------------------------------------
@@ -133,23 +231,22 @@ GET /test/_mget?stored_fields=field1,field2
 {
     "docs" : [
         {
-            "_id" : "1" <1>
+            "_id" : "1"
         },
         {
             "_id" : "2",
-            "stored_fields" : ["field3", "field4"] <2>
+            "stored_fields" : ["field3", "field4"]
         }
     ]
 }
 --------------------------------------------------
-<1> Returns `field1` and `field2`
-<2> Returns `field3` and `field4`
 
-[float]
 [[mget-routing]]
-==== Routing
+===== Specify document routing
 
-You can also specify a routing value as a parameter:
+If routing is used during indexing, you need to specify the routing value to retrieve documents. 
+For example, the following request fetches `test/_doc/2`  from the shard corresponding to routing key `key1`,
+and fetches `test/_doc/1` from the shard corresponding to routing key `key2`.
 
 [source,console]
 --------------------------------------------------
@@ -167,18 +264,4 @@ GET /_mget?routing=key1
         }
     ]
 }
---------------------------------------------------
-
-In this example, document `test/_doc/2` will be fetched from the shard corresponding to routing key `key1` but
-document `test/_doc/1` will be fetched from the shard corresponding to routing key `key2`.
-
-[float]
-[[mget-security]]
-==== Security
-
-See <<url-access-control>>.
-
-[float]
-[[multi-get-partial-responses]]
-==== Partial responses
-To ensure fast responses, the multi get API will respond with partial results if one or more shards fail. See <<shard-failures, Shard failures>> for more information.
+--------------------------------------------------

docs/reference/rest-api/common-parms.asciidoc

@@ -486,6 +486,12 @@ tag::query[]
 <<query-dsl,Query DSL>>.
 end::query[]
 
+tag::realtime[]
+`realtime`::
+(Optional, boolean) Set to `false` to disable real time GET
+(default: `true`). See <<realtime>>.
+end::realtime[]
+
 tag::refresh[]
 `refresh`::
 (Optional, enum) If `true`, {es} refreshes the affected shards to make this
@@ -616,6 +622,12 @@ tag::stats[]
 purposes.
 end::stats[]
 
+tag::stored_fields[]
+`stored_fields`::
+(Optional, boolean) If `true`, retrieves the document fields stored in the
+index rather than the document `_source`. Defaults to `false`.
+end::stored_fields[]
+
 tag::target-index[]
 `<target-index>`::
 +
@@ -700,6 +712,6 @@ end::wait_for_active_shards[]
 
 tag::wait_for_completion[]
 `wait_for_completion`::
-(Optional, boolean) Should the request block until the operation is 
-complete. Defaults to `true`.
+(Optional, boolean) If `true`, the request blocks until the operation is complete. 
+Defaults to `true`.
 end::wait_for_completion[]