[DOCS] Reformat put pipeline API (#47171) (#47397)

Author: jrodewig

docs/reference/ingest/apis/put-pipeline.asciidoc

@@ -1,10 +1,14 @@
 [[put-pipeline-api]]
-=== Put Pipeline API
+=== Put pipeline API
+++++
+<titleabbrev>Put pipeline</titleabbrev>
+++++
 
-The put pipeline API adds pipelines and updates existing pipelines in the cluster.
+Creates or updates an ingest pipeline.
+Changes made using this API take effect immediately.
 
 [source,js]
---------------------------------------------------
+----
 PUT _ingest/pipeline/my-pipeline-id
 {
   "description" : "describe pipeline",
@@ -17,17 +21,74 @@ PUT _ingest/pipeline/my-pipeline-id
     }
   ]
 }
---------------------------------------------------
+----
 // CONSOLE
 
-[float]
+
+[[put-pipeline-api-request]]
+==== {api-request-title}
+
+`PUT /_ingest/pipeline/<pipeline>`
+
+
+[[put-pipeline-api-path-params]]
+==== {api-path-parms-title}
+
+`<pipeline>`::
+(Required, string) ID of the ingest pipeline to create or update.
+
+
+[[put-pipeline-api-query-params]]
+==== {api-query-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout]
+
+
+[[put-pipeline-api-response-body]]
+==== {api-response-body-title}
+
+`description`::
+(Required, string)
+Description of the ingest pipeline.
+
+`processors`::
++
+--
+(Required, array of <<ingest-processors,processor objects>>)
+Array of processors used to pre-process documents
+before indexing.
+
+Processors are executed in the order provided.
+
+See <<ingest-processors>> for processor object definitions
+and a list of built-in processors.
+--
+
+`version`::
++
+--
+(Optional, integer)
+Optional version number used by external systems to manage ingest pipelines.
+
+Versions are not used or validated by {es};
+they are intended for external management only.
+--
+
+
+[[put-pipeline-api-example]]
+==== {api-examples-title}
+
+
 [[versioning-pipelines]]
-==== Pipeline versioning
+===== Pipeline versioning
+
+When creating or updating an ingest pipeline,
+you can specify an optional `version` parameter.
+The version is useful for managing changes to pipeline
+and viewing the current pipeline for an ingest node.
 
-Pipelines can optionally add a `version` number, which can be any integer value,
-in order to simplify pipeline management by external systems. The `version`
-field is completely optional and it is meant solely for external management of
-pipelines.
+The following request sets a version number of `123`
+for `my-pipeline-id`.
 
 [source,js]
 --------------------------------------------------
@@ -47,8 +108,8 @@ PUT /_ingest/pipeline/my-pipeline-id
 --------------------------------------------------
 // CONSOLE
 
-To unset a `version`, simply replace the pipeline without specifying
-one.
+To unset the version number,
+replace the pipeline without specifying a `version` parameter.
 
 [source,js]
 --------------------------------------------------
@@ -67,8 +128,7 @@ PUT /_ingest/pipeline/my-pipeline-id
 --------------------------------------------------
 // CONSOLE
 
-//////////////////////////
-
+////
 [source,js]
 --------------------------------------------------
 DELETE /_ingest/pipeline/my-pipeline-id
@@ -83,8 +143,4 @@ DELETE /_ingest/pipeline/my-pipeline-id
 }
 --------------------------------------------------
 // TESTRESPONSE
-
-//////////////////////////
-
-NOTE: The put pipeline API also instructs all ingest nodes to reload their in-memory representation of pipelines, so that
-      pipeline changes take effect immediately.
+////