Docs for data stream REST APIs (#55557)

docs/reference/indices.asciidoc

@@ -2,7 +2,7 @@
 == Index APIs
 
 Index APIs are used to manage individual indices,
-index settings, aliases, mappings, and index templates.
+index settings, data streams, aliases, mappings, and index templates.
 
 [float]
 [[index-management]]
@@ -30,6 +30,13 @@ index settings, aliases, mappings, and index templates.
 * <<indices-get-mapping>>
 * <<indices-get-field-mapping>>
 
+[float]
+[[data-stream-management]]
+=== Data stream management:
+* <<indices-create-data-stream>>
+* <<indices-delete-data-stream>>
+* <<indices-get-data-stream>>
+
 [float]
 [[alias-management]]
 === Alias management:
@@ -149,3 +156,9 @@ include::indices/apis/unfreeze.asciidoc[]
 include::indices/aliases.asciidoc[]
 
 include::indices/update-settings.asciidoc[]
+
+include::indices/create-data-stream.asciidoc[]
+
+include::indices/get-data-stream.asciidoc[]
+
+include::indices/delete-data-stream.asciidoc[]

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

@@ -0,0 +1,81 @@
+[[indices-create-data-stream]]
+=== Create data stream API
+++++
+<titleabbrev>Create data stream</titleabbrev>
+++++
+
+Creates a new data stream.
+
+Data streams provide a convenient way to ingest, search, and manage time series
+data. Documents containing time series data may be indexed directly into a data
+stream and searched through the data stream. Behind the scenes, data streams
+contain one or more hidden backing indices and a generation attribute that
+indicates which of the backing indices is the write index, the index into which
+documents will be ingested.
+
+Backing indices are generated with the naming convention
+`<data-stream-name>-zzzzzz` where `zzzzzz` is the six-digit, zero-padded
+generation of the data stream. For example, a data stream named
+`web-server-logs` with a generation of 34 would have a write index named
+`web-server-logs-000034`. While nothing prevents backing indices from being
+addressed directly, data streams are integrated with the
+<<indices-rollover-index, rollover index API>> and
+<<index-lifecycle-management, index lifecycle management (ILM)>> to facilitate
+the management of the time series data contained in their backing indices.
+
+[source,console]
+--------------------------------------------------
+PUT _data_stream/my-data-stream
+{
+  "timestamp_field": "@timestamp"
+}
+--------------------------------------------------
+
+////
+[source,console]
+-----------------------------------
+DELETE /_data_stream/my-data-stream
+-----------------------------------
+// TEST[continued]
+////
+
+[[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.
+
+[[indices-create-data-stream-api-path-params]]
+==== {api-path-parms-title}
+
+`<data-stream>`::
++
+--
+(Required, string) Name of the data stream to create.
+
+Data stream names must meet the following criteria:
+
+- Lowercase only
+- Cannot include `\`, `/`, `*`, `?`, `"`, `<`, `>`, `|`, ` ` (space character),
+`,`, `#`, `:`
+- Cannot start with `-`, `_`, `+`, `.`
+- Cannot be `.` or `..`
+- Cannot be longer than 255 bytes (note it is bytes, so multi-byte characters
+will count towards the 255 limit faster)
+--
+
+[[indices-create-data-stream-api-request-body]]
+==== {api-request-body-title}
+
+`timestamp_field`::
+(Required, string) The name of the timestamp field. This field must be present
+in all documents indexed into the data stream and must be of type
+<<date, `date`>> or <<date_nanos, `date_nanos`>>.
+

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

@@ -0,0 +1,36 @@
+[[indices-delete-data-stream]]
+=== Delete data stream API
+++++
+<titleabbrev>Delete data stream</titleabbrev>
+++++
+
+Deletes an existing data stream along with its backing indices.
+
+////
+[source,console]
+-----------------------------------
+PUT /_data_stream/my-data-stream
+{
+  "timestamp_field" : "@timestamp"
+}
+-----------------------------------
+// TESTSETUP
+////
+
+[source,console]
+--------------------------------------------------
+DELETE _data_stream/my-data-stream
+--------------------------------------------------
+
+
+[[delete-data-stream-api-request]]
+==== {api-request-title}
+
+`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.

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

@@ -0,0 +1,91 @@
+[[indices-get-data-stream]]
+=== Get data stream API
+++++
+<titleabbrev>Get data stream</titleabbrev>
+++++
+
+Returns information about one or more data streams.
+
+////
+[source,console]
+-----------------------------------
+PUT /_data_stream/my-data-stream
+{
+  "timestamp_field" : "@timestamp"
+}
+-----------------------------------
+// TESTSETUP
+////
+
+////
+[source,console]
+-----------------------------------
+DELETE /_data_stream/my-data-stream
+-----------------------------------
+// TEARDOWN
+////
+
+[source,console]
+--------------------------------------------------
+GET _data_streams/my-data-stream
+--------------------------------------------------
+// TEST[skip_shard_failures]
+
+[[get-data-stream-api-request]]
+==== {api-request-title}
+
+`GET _data_streams/<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.
+--
+
+[[get-data-stream-api-example]]
+==== {api-examples-title}
+
+[[get-data-stream-basic-example]]
+===== Basic example
+
+[source,console]
+--------------------------------------------------
+GET _data_streams/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>
+      {
+        "index_name" : "my-data-stream-000001",
+        "index_uuid" : "DXAE-xcCQTKF93bMm9iawA"
+      },
+      {
+        "index_name" : "my-data-stream-000002",
+        "index_uuid" : "Wzxq0VhsQKyPxHhaK3WYAg"
+      }
+    ],
+    "generation" : 2 <4>
+  }
+]
+--------------------------------------------------
+// TESTRESPONSE[skip:unable to assert responses with top level array]
+
+<1> Name of the data stream
+<2> The name of the timestamp field for the data stream
+<3> List of backing indices
+<4> Current generation for the data stream
+

docs/reference/redirects.asciidoc

@@ -389,7 +389,8 @@ coming::[7.x]
 [role="exclude",id="data-streams"]
 === Data stream APIs
 
-coming::[7.x]
+See <<indices-create-data-stream>>, <<indices-get-data-stream>>, and
+<<indices-delete-data-stream>>.
 
 [role="exclude",id="modules-indices"]
 === Indices module