Document Logstash Centralized Configuration Management HTTP APIs (#17706

)

* Starting to document Logstash config management APIS

* Removing copy pasta

* Adding delete pipeline API doc

* Mention updates in Create Pipeline API doc

* Capitalization fix

* Adding Retrieve Pipeline API doc

* Adding List Pipelines API doc

* Fixing typos

* Fixing DELETE pipeline API response code

* Add description field to GET pipeline response

* Update PUT pipeline API response to match implementation

* Fixing and annotating GET pipelines response

* Add AIP doc reference to index

* Adding xpack role

* Adding floats

* Missed list item

* Fixing rebase auto-merge

* Adding intro section to Logstash Configuration Management API page

* Bolding "experimental"

* Fixing typo

docs/api.asciidoc

@@ -28,6 +28,9 @@ entirely.
 == APIs
 
 * <<saved-objects-api>>
+* <<logstash-configuration-management-api>>
 --
 
-include::api/saved-objects.asciidoc[]
+include::api/saved-objects.asciidoc[]
+include::api/logstash-configuration-management.asciidoc[]
+

docs/api/logstash-configuration-management.asciidoc

@@ -0,0 +1,20 @@
+[role="xpack"]
+[[logstash-configuration-management-api]]
+== Logstash Configuration Management API
+
+The Logstash configuration management API allows users to programmatically integrate with the
+Logstash configuration management feature.
+
+Traditionally users would perform this integration by accessing the the `.logstash` index
+directly. *Do not do this!* The structure of this index is subject to change, which could
+cause your integration to break. Instead, use the following API.
+
+* <<logstash-configuration-management-api-create>>
+* <<logstash-configuration-management-api-retrieve>>
+* <<logstash-configuration-management-api-delete>>
+* <<logstash-configuration-management-api-list>>
+
+include::logstash-configuration-management/create.asciidoc[]
+include::logstash-configuration-management/retrieve.asciidoc[]
+include::logstash-configuration-management/delete.asciidoc[]
+include::logstash-configuration-management/list.asciidoc[]

docs/api/logstash-configuration-management/create.asciidoc

@@ -0,0 +1,50 @@
+[role="xpack"]
+[[logstash-configuration-management-api-create]]
+=== Create Pipeline
+
+experimental[This functionality is *experimental* and may be changed or removed completely in a future release.]
+
+The Create Pipeline API enables you to create a centrally-managed Logstash pipeline. You can also use
+it to update an existing pipeline.
+
+[float]
+==== Request
+
+`PUT /api/logstash/pipeline/<id>`
+
+[float]
+==== Path Parameters
+
+`id` (required)::
+  (string) ID for pipeline. Only alphanumeric characters, hyphens, and underscores may be used.
+
+
+[float]
+==== Request Body
+
+`description` (optional)::
+  (string) Description for the pipeline
+
+`pipeline` (required)::
+  (string) Pipeline definition
+
+`settings` (optional)::
+  (object) Pipeline settings. Supported settings, represented as object keys, are `pipeline.workers`, `pipeline.batch.size`, `pipeline.batch.delay`, `queue.type`, `queue.max_bytes`, and `queue.checkpoint.writes`
+
+
+[float]
+==== Examples
+
+[source,js]
+--------------------------------------------------
+PUT api/logstash/pipeline/hello-world
+{
+  "pipeline": "input { stdin {} } output { stdout {} }",
+  "settings": {
+    "queue.type": "persistent"
+  }
+}
+--------------------------------------------------
+// KIBANA
+
+A successful call returns an HTTP `204 No Content` response.

docs/api/logstash-configuration-management/delete.asciidoc

@@ -0,0 +1,30 @@
+[role="xpack"]
+[[logstash-configuration-management-api-delete]]
+=== Delete Pipeline
+
+experimental[This functionality is *experimental* and may be changed or removed completely in a future release.]
+
+The Delete Pipeline API enables you to delete a centrally-managed Logstash pipeline.
+
+[float]
+==== Request
+
+`DELETE /api/logstash/pipeline/<id>`
+
+[float]
+==== Path Parameters
+
+`id` (required)::
+  (string) ID for pipeline.
+
+
+[float]
+==== Examples
+
+[source,js]
+--------------------------------------------------
+DELETE api/logstash/pipeline/hello-world
+--------------------------------------------------
+// KIBANA
+
+A successful call returns an HTTP `204 No Content` response.

docs/api/logstash-configuration-management/list.asciidoc

@@ -0,0 +1,44 @@
+[role="xpack"]
+[[logstash-configuration-management-api-list]]
+=== List Pipelines
+
+experimental[This functionality is *experimental* and may be changed or removed completely in a future release.]
+
+The List Pipelines API enables you to list all centrally-managed Logstash pipelines.
+
+[float]
+==== Request
+
+`GET /api/logstash/pipelines`
+
+[float]
+==== Examples
+
+[source,js]
+--------------------------------------------------
+GET api/logstash/pipelines
+--------------------------------------------------
+// KIBANA
+
+A successful call returns a JSON structure similar to the following example:
+
+[source,js]
+--------------------------------------------------
+{
+  "pipelines": [
+    {
+      "id": "hello-world",
+      "description": "Just a simple pipeline",
+      "last_modified": "2018-04-14T12:23:29.772Z",
+      "username": "elastic" <1>
+    },
+    {
+      "id": "sleepy-pipeline",
+      "description": "",
+      "last_modified": "2018-03-24T03:41:30.554Z"
+    }
+  ]
+}
+--------------------------------------------------
+
+<1> The username property may or may not be present, depending on whether Elastic Security was enabled when the pipeline was created or last updated.

docs/api/logstash-configuration-management/retrieve.asciidoc

@@ -0,0 +1,42 @@
+[role="xpack"]
+[[logstash-configuration-management-api-retrieve]]
+=== Retrieve Pipeline
+
+experimental[This functionality is *experimental* and may be changed or removed completely in a future release.]
+
+The Retrieve Pipeline API enables you to retrieve a centrally-managed Logstash pipeline.
+
+[float]
+==== Request
+
+`GET /api/logstash/pipeline/<id>`
+
+[float]
+==== Path Parameters
+
+`id` (required)::
+  (string) ID for pipeline.
+
+[float]
+==== Examples
+
+[source,js]
+--------------------------------------------------
+GET api/logstash/pipeline/hello-world
+--------------------------------------------------
+// KIBANA
+
+A successful call returns a JSON structure similar to the following example:
+
+[source,js]
+--------------------------------------------------
+{
+  "id": "hello-world",
+  "description": "Just a simple pipeline",
+  "username": "elastic",
+  "pipeline": "input { stdin {} } output { stdout {} }",
+  "settings": {
+    "queue.type": "persistent"
+  }
+}
+--------------------------------------------------