From dbd21c325d5aabd4b6149ede22d4a5d871214a83 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C4=93teris=20Caune?= Date: Wed, 29 Jan 2020 12:43:35 +0200 Subject: [PATCH] Docs: "HTTP API" page --- hc/front/views.py | 1 + static/css/docs.css | 4 +- templates/docs/http_api.html | 94 ++++++++++++++++++++ templates/docs/http_api.md | 107 +++++++++++++++++++++++ templates/docs/monitoring_cron_jobs.html | 4 +- templates/docs/monitoring_cron_jobs.md | 4 +- templates/front/base_docs.html | 11 ++- 7 files changed, 215 insertions(+), 10 deletions(-) create mode 100644 templates/docs/http_api.html create mode 100644 templates/docs/http_api.md diff --git a/hc/front/views.py b/hc/front/views.py index fc748050..a41af575 100644 --- a/hc/front/views.py +++ b/hc/front/views.py @@ -272,6 +272,7 @@ def serve_doc(request, doc="introduction"): content = open(path, "r", encoding="utf-8").read() content = content.replace("SITE_NAME", settings.SITE_NAME) content = content.replace("PING_URL", settings.PING_ENDPOINT + "your-uuid-here") + content = content.replace("PING_ENDPOINT", settings.PING_ENDPOINT) content = content.replace("IMG_URL", os.path.join(settings.STATIC_URL, "img/docs")) content = content.replace( "PING_EMAIL", "your-uuid-here@%s" % settings.PING_EMAIL_DOMAIN diff --git a/static/css/docs.css b/static/css/docs.css index 76285632..f4ee4707 100644 --- a/static/css/docs.css +++ b/static/css/docs.css @@ -83,8 +83,8 @@ a.section:hover { border-radius: 4px; } -.docs-content { - line-height: 2; +.docs-content, .docs-content .table td { + line-height: 1.8; } .docs-content h1 { diff --git a/templates/docs/http_api.html b/templates/docs/http_api.html new file mode 100644 index 00000000..75a42234 --- /dev/null +++ b/templates/docs/http_api.html @@ -0,0 +1,94 @@ +

HTTP API

+

The SITE_NAME pinging API is used for submitting success, failure and job start +signals from the monitored systems.

+

General Notes

+

All ping endpoints support:

+ +

Successful responses will have the "200 OK" HTTP response status code and a short +and simple string "OK" in the response body.

+

Signal Success ("ping")

+
HEAD|GET|POST PING_ENDPOINT{uuid}
+
+ + +

Signals to SITE_NAME that the job has completed successfully (or, for +continuously running processes, is still running and healthy). The uuid parameter +is unique for each check.

+

Example

+
GET /5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278 HTTP/1.0
+Host: hc-ping.com
+
+ + +
HTTP/1.1 200 OK
+Server: nginx
+Date: Wed, 29 Jan 2020 09:58:23 GMT
+Content-Type: text/plain; charset=utf-8
+Content-Length: 2
+Connection: close
+Access-Control-Allow-Origin: *
+
+OK
+
+ + +

Signal Failure

+
HEAD|GET|POST PING_ENDPOINT{uuid}/fail
+
+ + +

Signals to SITE_NAME that the job has failed. Actively signalling a failure +minimizes the delay from your monitored service failing to you receiving an alert.

+

Example

+
GET /5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278/fail HTTP/1.0
+Host: hc-ping.com
+
+ + +
HTTP/1.1 200 OK
+Server: nginx
+Date: Wed, 29 Jan 2020 09:58:23 GMT
+Content-Type: text/plain; charset=utf-8
+Content-Length: 2
+Connection: close
+Access-Control-Allow-Origin: *
+
+OK
+
+ + +

Signal a Start

+
HEAD|GET|POST PING_ENDPOINT{uuid}/fail
+
+ + +

Sends a "job has started!" message to SITE_NAME. This is +optional but enables a few extra features:

+ +

Example

+
GET /5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278/start HTTP/1.0
+Host: hc-ping.com
+
+ + +
HTTP/1.1 200 OK
+Server: nginx
+Date: Wed, 29 Jan 2020 09:58:23 GMT
+Content-Type: text/plain; charset=utf-8
+Content-Length: 2
+Connection: close
+Access-Control-Allow-Origin: *
+
+OK
+
\ No newline at end of file diff --git a/templates/docs/http_api.md b/templates/docs/http_api.md new file mode 100644 index 00000000..fa469adb --- /dev/null +++ b/templates/docs/http_api.md @@ -0,0 +1,107 @@ +# HTTP API + +The SITE_NAME pinging API is used for submitting success, failure and job start +signals from the monitored systems. + +## General Notes + +All ping endpoints support: + +* HTTP and HTTPS +* HTTP 1.0, HTTP 1.1 and HTTP 2 +* IPv4 and IPv6 +* HEAD, GET and POST requests methods. The HTTP POST requests +can optionally include diagnostic information in the request body. +If the request body looks like a UTF-8 string, SITE_NAME stores the request body +(limited to first 10KB for each received ping). + +Successful responses will have the "200 OK" HTTP response status code and a short +and simple string "OK" in the response body. + +## Signal Success ("ping") + +```text +HEAD|GET|POST PING_ENDPOINT{uuid} +``` + +Signals to SITE_NAME that the job has completed successfully (or, for +continuously running processes, is still running and healthy). The `uuid` parameter +is unique for each check. + +**Example** + +```http +GET /5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278 HTTP/1.0 +Host: hc-ping.com +``` + +```http +HTTP/1.1 200 OK +Server: nginx +Date: Wed, 29 Jan 2020 09:58:23 GMT +Content-Type: text/plain; charset=utf-8 +Content-Length: 2 +Connection: close +Access-Control-Allow-Origin: * + +OK +``` + +## Signal Failure + +```text +HEAD|GET|POST PING_ENDPOINT{uuid}/fail +``` + +Signals to SITE_NAME that the job has failed. Actively signalling a failure +minimizes the delay from your monitored service failing to you receiving an alert. + +**Example** + +```http +GET /5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278/fail HTTP/1.0 +Host: hc-ping.com +``` + +``` +HTTP/1.1 200 OK +Server: nginx +Date: Wed, 29 Jan 2020 09:58:23 GMT +Content-Type: text/plain; charset=utf-8 +Content-Length: 2 +Connection: close +Access-Control-Allow-Origin: * + +OK +``` + +## Signal a Start + +```text +HEAD|GET|POST PING_ENDPOINT{uuid}/fail +``` + +Sends a "job has started!" message to SITE_NAME. This is +optional but enables a few extra features: + +* SITE_NAME will measure and display job execution times +* SITE_NAME will detect if the job runs longer than its configured grace time + +**Example** + +```http +GET /5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278/start HTTP/1.0 +Host: hc-ping.com +``` + +``` +HTTP/1.1 200 OK +Server: nginx +Date: Wed, 29 Jan 2020 09:58:23 GMT +Content-Type: text/plain; charset=utf-8 +Content-Length: 2 +Connection: close +Access-Control-Allow-Origin: * + +OK +``` diff --git a/templates/docs/monitoring_cron_jobs.html b/templates/docs/monitoring_cron_jobs.html index 9eb56dca..928c98da 100644 --- a/templates/docs/monitoring_cron_jobs.html +++ b/templates/docs/monitoring_cron_jobs.html @@ -13,8 +13,8 @@ after a job completes.

script is presumably a headless, background process. Even if it works correctly currently, it can start silently failing in future, without anyone noticing.

-

You can set up SITE_NAME to notify you whenever the backup script doesn't -run on time and complete successfully. Here are the steps to do that.

+

You can set up SITE_NAME to notify you whenever the backup script does not +run on time or does not complete successfully. Here are the steps to do that.

  1. If you have not already, sign up for a free SITE_NAME account.

    diff --git a/templates/docs/monitoring_cron_jobs.md b/templates/docs/monitoring_cron_jobs.md index 8d691c34..8bb80d30 100644 --- a/templates/docs/monitoring_cron_jobs.md +++ b/templates/docs/monitoring_cron_jobs.md @@ -17,8 +17,8 @@ script is presumably a headless, background process. Even if it works correctly currently, it can start silently failing in future, without anyone noticing. -You can set up SITE_NAME to notify you whenever the backup script doesn't -run on time and complete successfully. Here are the steps to do that. +You can set up SITE_NAME to notify you whenever the backup script does not +run on time or does not complete successfully. Here are the steps to do that. 1. If you have not already, sign up for a free SITE_NAME account. diff --git a/templates/front/base_docs.html b/templates/front/base_docs.html index 67b08803..0e564f92 100644 --- a/templates/front/base_docs.html +++ b/templates/front/base_docs.html @@ -13,11 +13,9 @@
    2. {% include "front/docs_nav_item.html" with slug="monitoring_cron_jobs" title="Monitoring cron jobs" %} {% include "front/docs_nav_item.html" with slug="configuring_checks" title="Configuring checks" %} - {% include "front/docs_nav_item.html" with slug="signalling_failures" title="Signalling failures" %} - {% include "front/docs_nav_item.html" with slug="measuring_script_run_time" title="Measuring script run time" %} - {% include "front/docs_nav_item.html" with slug="attaching_logs" title="Attaching logs" %}
  2. Pinging Examples
    3. + {% include "front/docs_nav_item.html" with slug="http_api" title="HTTP API" %} {% include "front/docs_nav_item.html" with slug="bash" title="Shell Scripts" %} {% include "front/docs_nav_item.html" with slug="python" title="Python" %} {% include "front/docs_nav_item.html" with slug="ruby" title="Ruby" %} @@ -27,9 +25,14 @@ {% include "front/docs_nav_item.html" with slug="powershell" title="PowerShell" %} {% include "front/docs_nav_item.html" with slug="email" title="Email" %} +
  3. Guides
    4. + {% include "front/docs_nav_item.html" with slug="signalling_failures" title="Signalling failures" %} + {% include "front/docs_nav_item.html" with slug="measuring_script_run_time" title="Measuring script run time" %} + {% include "front/docs_nav_item.html" with slug="attaching_logs" title="Attaching logs" %} +
  4. Developer Tools
    5. - API + Management API {% include "front/docs_nav_item.html" with slug="resources" title="Third-party resources" %}