[Docs/Reporting] More information about HTTP / script stuff (#41200) (#…

…41523)

* [Docs/Reporting] More information about HTTP / script stuff

* "post url" formatting consistency

* consistent wording from 1 paragraph to another

* Update docs/reporting/response-codes.asciidoc

Co-Authored-By: gchaps <33642766+gchaps@users.noreply.github.com>

* pr feedback

* subs=attributes, version in command example

* "Retry-After" content

* another feedback

docs/reporting/automating-report-generation.asciidoc

@@ -2,7 +2,7 @@
 [[automating-report-generation]]
 == Automating Report Generation
 You can automatically generate reports with {watcher}, or by submitting
-HTTP POST requests from a script.
+HTTP `POST` requests from a script.
 
 include::report-intervals.asciidoc[]
 
@@ -38,6 +38,11 @@ include::watch-example.asciidoc[]
 
 include::script-example.asciidoc[]
 
+[float]
+=== HTTP Response Codes
+
+include::response-codes.asciidoc[]
+
 [float]
 == Deprecated Report URLs
 

docs/reporting/response-codes.asciidoc

@@ -0,0 +1,23 @@
+The Reporting APIs use HTTP response codes to give feedback. In automation,
+this helps external systems track the various possible job states:
+
+- **`200` (OK)**: As expected, Kibana returns `200` status in the response for
+  successful requests to queue or download reports.
++
+NOTE: Kibana will send a `200` response status for successfully queuing a Reporting job via
+the POST URL. This is true even if the job somehow fails later, since report
+generation happens asynchronously from queuing.
+
+- **`400` (Bad Request)**: When sending requests to the POST URL, if you don't use
+  `POST` as the HTTP method, or if your request is missing the `kbn-version` header,
+  Kibana will return a code `400` status response for the request.
+
+- **`503` (Service Unavailable)**: When using the `path` to request the download, you
+  will get a `503` status response if report generation hasn't completed yet. The
+  response will include a `Retry-After` header. You can set the script to wait the
+  number of seconds in the `Retry-After` header, and then repeat if needed, until the
+  report is complete.
+
+- **`500` (Internal Server Error)**: When using the `path` to request the download, you
+  will get a `500` status response if the report isn't available due to an error when
+  generating the report. More information is available at **Management > Kibana > Reporting**.

docs/reporting/script-example.asciidoc

@@ -1,28 +1,30 @@
-To automatically generate reports from a script, you'll make a request to the POST URL.
+To automatically generate reports from a script, you'll make a request to the `POST` URL.
 The response from this request will be JSON, and will contain a `path` property with a
-URL to use to download the generated report when it is complete.
+URL to use to download the generated report. Use the `GET` method in the HTTP request to
+download the report.
 
-The request method must be POST and it must include a `kbn-version` header for Kibana
+The request method must be `POST` and it must include a `kbn-version` header for Kibana
 to allow the request.
 
-The following example queues CSV report generation using the POST URL with cURL:
+The following example queues CSV report generation using the `POST` URL with cURL:
 
-[source,shell]
+["source","sh",subs="attributes"]
 ---------------------------------------------------------
 curl \
 -XPOST \ <1>
 -u elastic \ <2>
--H 'kbn-version: 8.0.0' \ <3>
+-H 'kbn-version: {version}' \ <3>
 'http://0.0.0.0:5601/api/reporting/generate/csv?jobParams=...' <4>
 ---------------------------------------------------------
 // CONSOLE
 
-<1> POST method is required.
+<1> `POST` method is required.
 <2> Provide user credentials for a user with permission to access Kibana and X-Pack reporting.
-<3> The `kbn-version` header is required for all POST requests to Kibana.
+<3> The `kbn-version` header is required for all `POST` requests to Kibana.
+**The value must match the dotted-numeral version of the Kibana instance.**
 <4> The POST URL. You can copy and paste the URL for any report from the Kibana UI.
 
-Here is an example response:
+Here is an example response for a successfully queued report:
 
 [source,json]
 ---------------------------------------------------------
@@ -45,16 +47,3 @@ Here is an example response:
 <1> The relative path on the Kibana host for downloading the report.
 <2> (Not included in the example) Internal representation of the reporting job, as
 found in the `.reporting-*` index.
-
-[IMPORTANT]
-===================
-When using the `path` to request the download, you will get a 503 (Service Unavailable)
-response if report generation hasn't completed yet. In that case, retry after the
-number of seconds in the `Retry-After` header in the download API response until the
-report is complete.
-
-If there was an error in generating the report, the download URL will return a 500
-(Internal Server Error) response. More information is available in the
-Reporting management page in Kibana: *Management > Kibana > Reporting*
-===================
-