[DOCS] Reformat get pipeline API (#47131)

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

@@ -1,15 +1,19 @@
 [[get-pipeline-api]]
-=== Get Pipeline API
+=== Get pipeline API
+++++
+<titleabbrev>Get pipeline</titleabbrev>
+++++
 
-The get pipeline API returns pipelines based on ID. This API always returns a local reference of the pipeline.
-
-//////////////////////////
+Returns information about one or more ingest pipelines.
+This API returns a local reference of the pipeline.
 
+////
 [source,console]
---------------------------------------------------
-PUT _ingest/pipeline/my-pipeline-id
+----
+PUT /_ingest/pipeline/my-pipeline-id
 {
   "description" : "describe pipeline",
+  "version" : 123,
   "processors" : [
     {
       "set" : {
@@ -19,23 +23,59 @@ PUT _ingest/pipeline/my-pipeline-id
     }
   ]
 }
---------------------------------------------------
+----
+////
+
+[source,console]
+----
+GET /_ingest/pipeline/my-pipeline-id
+----
+// TEST[continued]
+
+
+
+[[get-pipeline-api-request]]
+==== {api-request-title}
+
+`GET /_ingest/pipeline/<pipeline>`
+
+`GET /_ingest/pipeline`
+
+
+[[get-pipeline-api-path-params]]
+==== {api-path-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=path-pipeline]
+
+
+
+[[get-pipeline-api-query-params]]
+==== {api-query-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout]
+
 
-//////////////////////////
+[[get-pipeline-api-api-example]]
+==== {api-examples-title}
+
+
+[[get-pipeline-api-specific-ex]]
+===== Get information for a specific ingest pipeline
 
 [source,console]
---------------------------------------------------
-GET _ingest/pipeline/my-pipeline-id
---------------------------------------------------
+----
+GET /_ingest/pipeline/my-pipeline-id
+----
 // TEST[continued]
 
-Example response:
+The API returns the following response:
 
 [source,console-result]
---------------------------------------------------
+----
 {
   "my-pipeline-id" : {
     "description" : "describe pipeline",
+    "version" : 123,
     "processors" : [
       {
         "set" : {
@@ -46,73 +86,51 @@ Example response:
     ]
   }
 }
---------------------------------------------------
+----
 
-For each returned pipeline, the source and the version are returned.
-The version is useful for knowing which version of the pipeline the node has.
-You can specify multiple IDs to return more than one pipeline. Wildcards are also supported.
 
-[float]
-[[versioning-pipelines]]
-==== Pipeline Versioning
+[[get-pipeline-api-version-ex]]
+===== Get the version of an ingest pipeline
 
-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. To unset a `version`, simply replace the pipeline without specifying
-one.
+When you create or update 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.
 
-[source,console]
---------------------------------------------------
-PUT _ingest/pipeline/my-pipeline-id
-{
-  "description" : "describe pipeline",
-  "version" : 123,
-  "processors" : [
-    {
-      "set" : {
-        "field": "foo",
-        "value": "bar"
-      }
-    }
-  ]
-}
---------------------------------------------------
 
-To check for the `version`, you can
-<<common-options-response-filtering, filter responses>>
-using `filter_path` to limit the response to just the `version`:
+To check the pipeline version,
+use the `filter_path` query parameter
+to <<common-options-response-filtering, filter the response>>
+to only the version.
 
 [source,console]
---------------------------------------------------
+----
 GET /_ingest/pipeline/my-pipeline-id?filter_path=*.version
---------------------------------------------------
+----
 // TEST[continued]
 
-This should give a small response that makes it both easy and inexpensive to parse:
+The API returns the following response:
 
 [source,console-result]
---------------------------------------------------
+----
 {
   "my-pipeline-id" : {
     "version" : 123
   }
 }
---------------------------------------------------
-
-//////////////////////////
+----
 
+////
 [source,console]
---------------------------------------------------
+----
 DELETE /_ingest/pipeline/my-pipeline-id
---------------------------------------------------
+----
 // TEST[continued]
 
 [source,console-result]
---------------------------------------------------
+----
 {
 "acknowledged": true
 }
---------------------------------------------------
-
-//////////////////////////
+----
+////

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

@@ -19,6 +19,51 @@ PUT _ingest/pipeline/my-pipeline-id
 }
 --------------------------------------------------
 
+[float]
+[[versioning-pipelines]]
+==== Pipeline versioning
+
+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.
+
+[source,console]
+--------------------------------------------------
+PUT /_ingest/pipeline/my-pipeline-id
+{
+  "description" : "describe pipeline",
+  "version" : 123,
+  "processors" : [
+    {
+      "set" : {
+        "field": "foo",
+        "value": "bar"
+      }
+    }
+  ]
+}
+--------------------------------------------------
+
+To unset a `version`, simply replace the pipeline without specifying
+one.
+
+[source,console]
+--------------------------------------------------
+PUT /_ingest/pipeline/my-pipeline-id
+{
+  "description" : "describe pipeline",
+  "processors" : [
+    {
+      "set" : {
+        "field": "foo",
+        "value": "bar"
+      }
+    }
+  ]
+}
+--------------------------------------------------
+
 //////////////////////////
 
 [source,console]

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

@@ -385,6 +385,12 @@ tag::pipeline[]
 (Optional, string) ID of the pipeline to use to preprocess incoming documents.
 end::pipeline[]
 
+tag::path-pipeline[]
+`<pipeline>`::
+(Optional, string) Comma-separated list or wildcard expression of pipeline IDs
+used to limit the request.
+end::path-pipeline[]
+
 tag::preference[]
 `preference`::
 (Optional, string) Specifies the node or shard the operation should be