[DOCS] Reformat get pipeline API (#47131) (#47165)

elastic · Sep 26, 2019 · 8daa6b5 · 8daa6b5
1 parent 0bae950
commit 8daa6b5
Show file tree

Hide file tree

Showing 3 changed files with 79 additions and 21 deletions.
diff --git a/docs/reference/ingest/apis/get-pipeline.asciidoc b/docs/reference/ingest/apis/get-pipeline.asciidoc
@@ -1,15 +1,18 @@
 [[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,js]
 --------------------------------------------------
 PUT _ingest/pipeline/my-pipeline-id
 {
   "description" : "describe pipeline",
+  "version" : 123,
   "processors" : [
     {
       "set" : {
@@ -22,7 +25,12 @@ PUT _ingest/pipeline/my-pipeline-id
 --------------------------------------------------
 // CONSOLE
 
-//////////////////////////
+[[get-pipeline-api-api-example]]
+==== {api-examples-title}
+
+
+[[get-pipeline-api-specific-ex]]
+===== Get information for a specific ingest pipeline
 
 [source,js]
 --------------------------------------------------
@@ -31,13 +39,14 @@ GET _ingest/pipeline/my-pipeline-id
 // CONSOLE
 // TEST[continued]
 
-Example response:
+The API returns the following response:
 
 [source,js]
 --------------------------------------------------
 {
   "my-pipeline-id" : {
     "description" : "describe pipeline",
+    "version" : 123,
     "processors" : [
       {
         "set" : {
@@ -51,19 +60,14 @@ Example response:
 --------------------------------------------------
 // TESTRESPONSE
 
-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,js]
 --------------------------------------------------
@@ -83,9 +87,10 @@ PUT _ingest/pipeline/my-pipeline-id
 --------------------------------------------------
 // CONSOLE
 
-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,js]
 --------------------------------------------------
@@ -94,7 +99,7 @@ GET /_ingest/pipeline/my-pipeline-id?filter_path=*.version
 // CONSOLE
 // TEST[continued]
 
-This should give a small response that makes it both easy and inexpensive to parse:
+The API returns the following response:
 
 [source,js]
 --------------------------------------------------

diff --git a/docs/reference/ingest/apis/put-pipeline.asciidoc b/docs/reference/ingest/apis/put-pipeline.asciidoc
@@ -20,6 +20,53 @@ PUT _ingest/pipeline/my-pipeline-id
 --------------------------------------------------
 // CONSOLE
 
+[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,js]
+--------------------------------------------------
+PUT /_ingest/pipeline/my-pipeline-id
+{
+  "description" : "describe pipeline",
+  "version" : 123,
+  "processors" : [
+    {
+      "set" : {
+        "field": "foo",
+        "value": "bar"
+      }
+    }
+  ]
+}
+--------------------------------------------------
+// CONSOLE
+
+To unset a `version`, simply replace the pipeline without specifying
+one.
+
+[source,js]
+--------------------------------------------------
+PUT /_ingest/pipeline/my-pipeline-id
+{
+  "description" : "describe pipeline",
+  "processors" : [
+    {
+      "set" : {
+        "field": "foo",
+        "value": "bar"
+      }
+    }
+  ]
+}
+--------------------------------------------------
+// CONSOLE
+
 //////////////////////////
 
 [source,js]

diff --git a/docs/reference/rest-api/common-parms.asciidoc b/docs/reference/rest-api/common-parms.asciidoc
@@ -394,6 +394,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