From 122ec43c4860974c575869b25382a905ae6d42f8 Mon Sep 17 00:00:00 2001 From: Timothy Sullivan Date: Mon, 15 Jul 2019 12:37:04 -0700 Subject: [PATCH 1/8] [Docs/Reporting] More information about HTTP / script stuff --- .../automating-report-generation.asciidoc | 7 ++++- docs/reporting/response-codes.asciidoc | 23 ++++++++++++++ docs/reporting/script-example.asciidoc | 31 ++++++------------- 3 files changed, 39 insertions(+), 22 deletions(-) create mode 100644 docs/reporting/response-codes.asciidoc diff --git a/docs/reporting/automating-report-generation.asciidoc b/docs/reporting/automating-report-generation.asciidoc index 194702c96afe6..01b3f80853ef8 100644 --- a/docs/reporting/automating-report-generation.asciidoc +++ b/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 diff --git a/docs/reporting/response-codes.asciidoc b/docs/reporting/response-codes.asciidoc new file mode 100644 index 0000000000000..7174c14473c87 --- /dev/null +++ b/docs/reporting/response-codes.asciidoc @@ -0,0 +1,23 @@ +The Reporting APIs use HTTP response codes to indicate 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 execution 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. In that case, + retry after the number of seconds in the `Retry-After` header in the download API + response until the report is complete. + +- **`500` (Internal Server Error)**: If there was an error in generating the report, + the download URL will return a `500` status response. More information will be + available in the Reporting management page in Kibana: *Management > Kibana > + Reporting* diff --git a/docs/reporting/script-example.asciidoc b/docs/reporting/script-example.asciidoc index 8682578735b66..50fa471880a83 100644 --- a/docs/reporting/script-example.asciidoc +++ b/docs/reporting/script-example.asciidoc @@ -1,11 +1,12 @@ -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] --------------------------------------------------------- @@ -17,12 +18,13 @@ curl \ --------------------------------------------------------- // 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. -<4> The POST URL. You can copy and paste the URL for any report from the Kibana UI. +<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* -=================== - From dd5d5e872913f14624b7772e9c838a047ca13a33 Mon Sep 17 00:00:00 2001 From: Timothy Sullivan Date: Mon, 15 Jul 2019 14:45:02 -0700 Subject: [PATCH 2/8] "post url" formatting consistency --- docs/reporting/script-example.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reporting/script-example.asciidoc b/docs/reporting/script-example.asciidoc index 50fa471880a83..42b401a19132b 100644 --- a/docs/reporting/script-example.asciidoc +++ b/docs/reporting/script-example.asciidoc @@ -22,7 +22,7 @@ curl \ <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. **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. +<4> The POST URL. You can copy and paste the URL for any report from the Kibana UI. Here is an example response for a successfully queued report: From a6c5fde97c090a2b6c4c14012d7c95d33544ed9f Mon Sep 17 00:00:00 2001 From: Timothy Sullivan Date: Tue, 16 Jul 2019 10:16:47 -0700 Subject: [PATCH 3/8] consistent wording from 1 paragraph to another --- docs/reporting/response-codes.asciidoc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/reporting/response-codes.asciidoc b/docs/reporting/response-codes.asciidoc index 7174c14473c87..a14e90ad5f5e7 100644 --- a/docs/reporting/response-codes.asciidoc +++ b/docs/reporting/response-codes.asciidoc @@ -5,8 +5,8 @@ this helps external systems track the various possible job states: 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 execution happens -asynchronously from queuing. +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, @@ -17,7 +17,7 @@ asynchronously from queuing. retry after the number of seconds in the `Retry-After` header in the download API response until the report is complete. -- **`500` (Internal Server Error)**: If there was an error in generating the report, - the download URL will return a `500` status response. More information will be - available in the Reporting management page in Kibana: *Management > Kibana > - Reporting* +- **`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 will be available in the Reporting management + page in Kibana, at: *Management > Kibana > Reporting* From 6eed80eaa88e4b156526d36a777fbd039b3b9c08 Mon Sep 17 00:00:00 2001 From: Tim Sullivan Date: Thu, 18 Jul 2019 10:49:01 -0700 Subject: [PATCH 4/8] Update docs/reporting/response-codes.asciidoc Co-Authored-By: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/reporting/response-codes.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reporting/response-codes.asciidoc b/docs/reporting/response-codes.asciidoc index a14e90ad5f5e7..b9a8b91d16feb 100644 --- a/docs/reporting/response-codes.asciidoc +++ b/docs/reporting/response-codes.asciidoc @@ -1,4 +1,4 @@ -The Reporting APIs use HTTP response codes to indicate to give feedback. In automation, +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 From 0dbc9752d372ac989089152fa41cb607ba6afbdc Mon Sep 17 00:00:00 2001 From: Timothy Sullivan Date: Thu, 18 Jul 2019 10:59:42 -0700 Subject: [PATCH 5/8] pr feedback --- docs/reporting/response-codes.asciidoc | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/reporting/response-codes.asciidoc b/docs/reporting/response-codes.asciidoc index b9a8b91d16feb..5d2535d03be65 100644 --- a/docs/reporting/response-codes.asciidoc +++ b/docs/reporting/response-codes.asciidoc @@ -12,12 +12,11 @@ generation happens asynchronously from queuing. `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. In that case, - retry after the number of seconds in the `Retry-After` header in the download API - response until the report is complete. +- **`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. Before + trying again to download the report, have your script wait for the amount of time + suggested in the `Retry-After` HTTP header of response with `503` status. - **`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 will be available in the Reporting management - page in Kibana, at: *Management > Kibana > Reporting* + generating the report. More information is available at **Management > Kibana > Reporting**. From f8373051acb5998f22783e8c5696fb4d0690fe01 Mon Sep 17 00:00:00 2001 From: Timothy Sullivan Date: Thu, 18 Jul 2019 14:04:00 -0700 Subject: [PATCH 6/8] subs=attributes, version in command example --- docs/reporting/script-example.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reporting/script-example.asciidoc b/docs/reporting/script-example.asciidoc index 42b401a19132b..88f48ad1d3182 100644 --- a/docs/reporting/script-example.asciidoc +++ b/docs/reporting/script-example.asciidoc @@ -8,12 +8,12 @@ to allow the request. 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 From 635313ba079936b2deba62ab905be2b862b299e6 Mon Sep 17 00:00:00 2001 From: Timothy Sullivan Date: Thu, 18 Jul 2019 14:04:23 -0700 Subject: [PATCH 7/8] "Retry-After" content --- docs/reporting/response-codes.asciidoc | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/reporting/response-codes.asciidoc b/docs/reporting/response-codes.asciidoc index 5d2535d03be65..e1f12e2d0b875 100644 --- a/docs/reporting/response-codes.asciidoc +++ b/docs/reporting/response-codes.asciidoc @@ -13,9 +13,10 @@ generation happens asynchronously from queuing. 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. Before - trying again to download the report, have your script wait for the amount of time - suggested in the `Retry-After` HTTP header of response with `503` status. + will get a `503` status response if report generation hasn't completed yet. The + response will include a `Retry-After` header. You can have your script wait the + suggested number of seconds provided in the `Retry-After` header, waiting as many + times as 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 From 5f4be8743ad8e4345a508d963ef77dd4525def7e Mon Sep 17 00:00:00 2001 From: Timothy Sullivan Date: Thu, 18 Jul 2019 14:24:21 -0700 Subject: [PATCH 8/8] another feedback --- docs/reporting/response-codes.asciidoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/reporting/response-codes.asciidoc b/docs/reporting/response-codes.asciidoc index e1f12e2d0b875..5ec9bf5300124 100644 --- a/docs/reporting/response-codes.asciidoc +++ b/docs/reporting/response-codes.asciidoc @@ -14,9 +14,9 @@ generation happens asynchronously from queuing. - **`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 have your script wait the - suggested number of seconds provided in the `Retry-After` header, waiting as many - times as needed, until the report is complete. + 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