[DOCS] Reformat data stream API docs (#58322) (#58334)

docs/reference/data-streams/data-stream-apis.asciidoc

@@ -1,14 +1,16 @@
 [[data-stream-apis]]
 == Data stream APIs
 
-The following APIs are available for managing data streams:
+The following APIs are available for managing <<data-streams,data streams>>:
 
-* To get information about data streams, use the <<indices-get-data-stream, get data stream API>>.
-* To delete data streams, use the <<indices-delete-data-stream, delete data stream API>>.
-* To manually create a data stream, use the <<indices-create-data-stream, create data stream API>>.
+* <<indices-create-data-stream>>
+* <<indices-delete-data-stream>>
+* <<indices-get-data-stream>>
+
+For concepts and tutorials, see <<data-streams>>.
 
 include::{es-repo-dir}/indices/create-data-stream.asciidoc[]
 
-include::{es-repo-dir}/indices/get-data-stream.asciidoc[]
-
 include::{es-repo-dir}/indices/delete-data-stream.asciidoc[]
+
+include::{es-repo-dir}/indices/get-data-stream.asciidoc[]

docs/reference/indices/create-data-stream.asciidoc

@@ -4,14 +4,15 @@
 <titleabbrev>Create data stream</titleabbrev>
 ++++
 
-Creates a new data stream.
+Creates a new <<data-streams,data stream>>.
 
-A data stream can only be created if the namespace it targets has a composable
-index template with a `data_stream` definition.
+Data streams require an associated <<indices-templates,composable template>>.
+See <<set-up-a-data-stream>>.
 
+////
 [source,console]
------------------------------------
-PUT _index_template/template
+----
+PUT /_index_template/template
 {
   "index_patterns": ["my-data-stream*"],
   "template": {
@@ -27,13 +28,13 @@ PUT _index_template/template
     "timestamp_field": "@timestamp"
   }
 }
------------------------------------
-// TEST
+----
+////
 
 [source,console]
---------------------------------------------------
-PUT _data_stream/my-data-stream
---------------------------------------------------
+----
+PUT /_data_stream/my-data-stream
+----
 // TEST[continued]
 
 ////
@@ -48,15 +49,7 @@ DELETE /_index_template/template
 [[indices-create-data-stream-request]]
 ==== {api-request-title}
 
-`PUT _data_stream/<data-stream>`
-
-[[indices-create-data-stream-desc]]
-==== {api-description-title}
-You can use the create data stream API to add a new data stream to an {es}
-cluster. When creating a data stream, you must specify the following:
-
-* The name of the data stream
-* The name of the timestamp field.
+`PUT /_data_stream/<data-stream>`
 
 [[indices-create-data-stream-api-path-params]]
 ==== {api-path-parms-title}

docs/reference/indices/delete-data-stream.asciidoc

@@ -4,12 +4,13 @@
 <titleabbrev>Delete data stream</titleabbrev>
 ++++
 
-Deletes an existing data stream along with its backing indices.
+Deletes one or more <<data-streams,data streams>> and their backing
+indices. See <<delete-a-data-stream>>.
 
 ////
 [source,console]
------------------------------------
-PUT _index_template/template
+----
+PUT /_index_template/template
 {
   "index_patterns": ["my-data-stream*"],
   "template": {
@@ -27,31 +28,33 @@ PUT _index_template/template
 }
 
 PUT /_data_stream/my-data-stream
------------------------------------
+----
 // TESTSETUP
 ////
 
 [source,console]
---------------------------------------------------
-DELETE _data_stream/my-data-stream
---------------------------------------------------
+----
+DELETE /_data_stream/my-data-stream
+----
 
 ////
 [source,console]
------------------------------------
+----
 DELETE /_index_template/template
------------------------------------
+----
 // TEST[continued]
 ////
 
 [[delete-data-stream-api-request]]
 ==== {api-request-title}
 
-`DELETE _data_stream/<data-stream>`
+`DELETE /_data_stream/<data-stream>`
 
 
 [[delete-data-stream-api-path-params]]
 ==== {api-path-parms-title}
 
 `<data-stream>`::
-(Required, string) Name or wildcard expression of data stream(s) to delete.
+(Required, string)
+Name of the data stream to delete.
+Wildcard (`*`) expressions are supported.

docs/reference/indices/get-data-stream.asciidoc

@@ -4,11 +4,12 @@
 <titleabbrev>Get data stream</titleabbrev>
 ++++
 
-Returns information about one or more data streams.
+Retrieves information about one or more <<data-streams,data streams>>.
+See <<get-info-about-a-data-stream>>.
 
 ////
 [source,console]
------------------------------------
+----
 PUT _index_template/template
 {
   "index_patterns": ["my-data-stream*"],
@@ -27,63 +28,57 @@ PUT _index_template/template
 }
 
 PUT /_data_stream/my-data-stream
------------------------------------
+----
 // TESTSETUP
 ////
 
 ////
 [source,console]
------------------------------------
+----
 DELETE /_data_stream/my-data-stream
 DELETE /_index_template/template
------------------------------------
+----
 // TEARDOWN
 ////
 
 [source,console]
---------------------------------------------------
-GET _data_stream/my-data-stream
---------------------------------------------------
+----
+GET /_data_stream/my-data-stream
+----
 // TEST[skip_shard_failures]
 
 [[get-data-stream-api-request]]
 ==== {api-request-title}
 
-`GET _data_stream/<data-stream>`
-
+`GET /_data_stream/<data-stream>`
 
 [[get-data-stream-api-path-params]]
 ==== {api-path-parms-title}
 
 `<data-stream>`::
-+
---
-(Required, string) Name or wildcard expression of the data stream(s) to
-retrieve.
---
+(Required, string)
+Name of the data stream to retrieve.
+Wildcard (`*`) expressions are supported.
 
 [[get-data-stream-api-example]]
 ==== {api-examples-title}
 
-[[get-data-stream-basic-example]]
-===== Basic example
-
 [source,console]
---------------------------------------------------
+----
 GET _data_stream/my-data-stream*
---------------------------------------------------
+----
 // TEST[continued]
 // TEST[skip_shard_failures]
 
 The API returns the following response:
 
 [source,console-result]
---------------------------------------------------
+----
 [
   {
-    "name" : "my-data-stream", <1>
-    "timestamp_field" : "@timestamp", <2>
-    "indices" : [ <3>
+    "name" : "my-data-stream",                      <1>
+    "timestamp_field" : "@timestamp",               <2>
+    "indices" : [                                   <3>
       {
         "index_name" : ".ds-my-data-stream-000001",
         "index_uuid" : "DXAE-xcCQTKF93bMm9iawA"
@@ -93,10 +88,10 @@ The API returns the following response:
         "index_uuid" : "Wzxq0VhsQKyPxHhaK3WYAg"
       }
     ],
-    "generation" : 2 <4>
+    "generation" : 2                                <4>
   }
 ]
---------------------------------------------------
+----
 // TESTRESPONSE[skip:unable to assert responses with top level array]
 
 <1> Name of the data stream