[DOCS] add a warning about bypassing PUT API's, update example respon…

…ses (elastic#42062)

Configurations are stored in the .data-frame-internal-1
index, but users should not add configurations directly to
the index as additional information to enable access control
is added. This adds a warning against allowing access to the
internal index.

docs/reference/data-frames/apis/get-transform-stats.asciidoc

@@ -65,27 +65,35 @@ The API returns the following results:
     {
       "id" : "ecommerce_transform",
       "state" : {
+        "task_state" : "started",
         "indexer_state" : "started",
-        "task_state": "started",
-        "current_position" : {
-          "customer_id" : "9"
-        },
-        "generation" : 1
+        "checkpoint" : 1,
+        "progress" : {
+          "total_docs" : 1220,
+          "docs_remaining" : 0,
+          "percent_complete" : 100.0
+        }
       },
       "stats" : {
-        "pages_processed" : 0,
-        "documents_processed" : 0,
-        "documents_indexed" : 0,
-        "trigger_count" : 0,
-        "index_time_in_ms" : 0,
-        "index_total" : 0,
+        "pages_processed" : 2,
+        "documents_processed" : 1220,
+        "documents_indexed" : 13,
+        "trigger_count" : 1,
+        "index_time_in_ms" : 19,
+        "index_total" : 1,
         "index_failures" : 0,
-        "search_time_in_ms" : 0,
-        "search_total" : 0,
+        "search_time_in_ms" : 52,
+        "search_total" : 2,
         "search_failures" : 0
+      },
+      "checkpointing" : {
+        "current" : {
+          "timestamp_millis" : 1557474786393
+        },
+        "operations_behind" : 0
       }
     }
   ]
 }
 ----
-// TESTRESPONSE
+// TESTRESPONSE

docs/reference/data-frames/apis/get-transform.asciidoc

@@ -75,10 +75,20 @@ The API returns the following results:
   "transforms" : [
     {
       "id" : "ecommerce_transform",
-      "source" : "kibana_sample_data_ecommerce",
-      "dest" : "kibana_sample_data_ecommerce_transform",
-      "query" : {
-        "match_all" : { }
+      "source" : {
+        "index" : [
+          "kibana_sample_data_ecommerce"
+        ],
+        "query" : {
+          "term" : {
+            "geoip.continent_name" : {
+              "value" : "Asia"
+            }
+          }
+        }
+      },
+      "dest" : {
+        "index" : "kibana_sample_data_ecommerce_transform"
       },
       "pivot" : {
         "group_by" : {
@@ -95,7 +105,8 @@ The API returns the following results:
             }
           }
         }
-      }
+      },
+      "description" : "Maximum priced ecommerce data by customer_id in Asia"
     }
   ]
 }

docs/reference/data-frames/apis/put-transform.asciidoc

@@ -15,7 +15,13 @@ Instantiates a {dataframe-transform}.
 
 `PUT _data_frame/transforms/<data_frame_transform_id>`
 
-//===== Description
+===== Description
+
+IMPORTANT:  You must use {kib} or this API to create a {dataframe-transform}.
+            Do not put a {dataframe-transform} directly into any
+            `.data-frame-internal*` indices using the Elasticsearch index API.
+            If {es} {security-features} are enabled, do not give users any
+            privileges on `.data-frame-internal*` indices.
 
 ==== Path Parameters
 
@@ -27,12 +33,12 @@ Instantiates a {dataframe-transform}.
 
 ==== Request Body
 
-`source`:: (object) The source configuration, consisting of `index` and optionally
+`source` (required):: (object) The source configuration, consisting of `index` and optionally
 a `query`.
 
-`dest`:: (object) The destination configuration, consisting of `index`.
+`dest` (required):: (object) The destination configuration, consisting of `index`.
 
-`pivot`:: Defines the pivot function `group by` fields and the aggregation to
+`pivot`:: (object) Defines the pivot function `group by` fields and the aggregation to
 reduce the data.
 
 `description`:: Optional free text description of the data frame transform