Docs: "HTTP API" page

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

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 {

templates/docs/http_api.html

@@ -0,0 +1,94 @@
+<h1>HTTP API</h1>
+<p>The SITE_NAME pinging API is used for submitting success, failure and job start
+signals from the monitored systems.</p>
+<h2>General Notes</h2>
+<p>All ping endpoints support:</p>
+<ul>
+<li>HTTP and HTTPS</li>
+<li>HTTP 1.0, HTTP 1.1 and HTTP 2</li>
+<li>IPv4 and IPv6</li>
+<li>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).</li>
+</ul>
+<p>Successful responses will have the "200 OK" HTTP response status code and a short
+and simple string "OK" in the response body.</p>
+<h2>Signal Success ("ping")</h2>
+<div class="highlight"><pre><span></span>HEAD|GET|POST PING_ENDPOINT{uuid}
+</pre></div>
+
+
+<p>Signals to SITE_NAME that the job has completed successfully (or, for
+continuously running processes, is still running and healthy). The <code>uuid</code> parameter
+is unique for each check.</p>
+<p><strong>Example</strong></p>
+<div class="highlight"><pre><span></span><span class="nf">GET</span> <span class="nn">/5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278</span> <span class="kr">HTTP</span><span class="o">/</span><span class="m">1.0</span>
+<span class="na">Host</span><span class="o">:</span> <span class="l">hc-ping.com</span>
+</pre></div>
+
+
+<div class="highlight"><pre><span></span><span class="kr">HTTP</span><span class="o">/</span><span class="m">1.1</span> <span class="m">200</span> <span class="ne">OK</span>
+<span class="na">Server</span><span class="o">:</span> <span class="l">nginx</span>
+<span class="na">Date</span><span class="o">:</span> <span class="l">Wed, 29 Jan 2020 09:58:23 GMT</span>
+<span class="na">Content-Type</span><span class="o">:</span> <span class="l">text/plain; charset=utf-8</span>
+<span class="na">Content-Length</span><span class="o">:</span> <span class="l">2</span>
+<span class="na">Connection</span><span class="o">:</span> <span class="l">close</span>
+<span class="na">Access-Control-Allow-Origin</span><span class="o">:</span> <span class="l">*</span>
+
+OK
+</pre></div>
+
+
+<h2>Signal Failure</h2>
+<div class="highlight"><pre><span></span>HEAD|GET|POST PING_ENDPOINT{uuid}/fail
+</pre></div>
+
+
+<p>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.</p>
+<p><strong>Example</strong></p>
+<div class="highlight"><pre><span></span><span class="nf">GET</span> <span class="nn">/5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278/fail</span> <span class="kr">HTTP</span><span class="o">/</span><span class="m">1.0</span>
+<span class="na">Host</span><span class="o">:</span> <span class="l">hc-ping.com</span>
+</pre></div>
+
+
+<div class="highlight"><pre><span></span><span class="nt">HTTP</span><span class="o">/</span><span class="nt">1</span><span class="p">.</span><span class="nc">1</span> <span class="nt">200</span> <span class="nt">OK</span>
+<span class="nt">Server</span><span class="o">:</span> <span class="nt">nginx</span>
+<span class="nt">Date</span><span class="o">:</span> <span class="nt">Wed</span><span class="o">,</span> <span class="nt">29</span> <span class="nt">Jan</span> <span class="nt">2020</span> <span class="nt">09</span><span class="p">:</span><span class="nd">58</span><span class="p">:</span><span class="nd">23</span> <span class="nt">GMT</span>
+<span class="nt">Content-Type</span><span class="o">:</span> <span class="nt">text</span><span class="o">/</span><span class="nt">plain</span><span class="o">;</span> <span class="nt">charset</span><span class="o">=</span><span class="nt">utf-8</span>
+<span class="nt">Content-Length</span><span class="o">:</span> <span class="nt">2</span>
+<span class="nt">Connection</span><span class="o">:</span> <span class="nt">close</span>
+<span class="nt">Access-Control-Allow-Origin</span><span class="o">:</span> <span class="o">*</span>
+
+<span class="nt">OK</span>
+</pre></div>
+
+
+<h2>Signal a Start</h2>
+<div class="highlight"><pre><span></span>HEAD|GET|POST PING_ENDPOINT{uuid}/fail
+</pre></div>
+
+
+<p>Sends a "job has started!" message to SITE_NAME. This is
+optional but enables a few extra features:</p>
+<ul>
+<li>SITE_NAME will measure and display job execution times</li>
+<li>SITE_NAME will detect if the job runs longer than its configured grace time</li>
+</ul>
+<p><strong>Example</strong></p>
+<div class="highlight"><pre><span></span><span class="nf">GET</span> <span class="nn">/5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278/start</span> <span class="kr">HTTP</span><span class="o">/</span><span class="m">1.0</span>
+<span class="na">Host</span><span class="o">:</span> <span class="l">hc-ping.com</span>
+</pre></div>
+
+
+<div class="highlight"><pre><span></span><span class="nt">HTTP</span><span class="o">/</span><span class="nt">1</span><span class="p">.</span><span class="nc">1</span> <span class="nt">200</span> <span class="nt">OK</span>
+<span class="nt">Server</span><span class="o">:</span> <span class="nt">nginx</span>
+<span class="nt">Date</span><span class="o">:</span> <span class="nt">Wed</span><span class="o">,</span> <span class="nt">29</span> <span class="nt">Jan</span> <span class="nt">2020</span> <span class="nt">09</span><span class="p">:</span><span class="nd">58</span><span class="p">:</span><span class="nd">23</span> <span class="nt">GMT</span>
+<span class="nt">Content-Type</span><span class="o">:</span> <span class="nt">text</span><span class="o">/</span><span class="nt">plain</span><span class="o">;</span> <span class="nt">charset</span><span class="o">=</span><span class="nt">utf-8</span>
+<span class="nt">Content-Length</span><span class="o">:</span> <span class="nt">2</span>
+<span class="nt">Connection</span><span class="o">:</span> <span class="nt">close</span>
+<span class="nt">Access-Control-Allow-Origin</span><span class="o">:</span> <span class="o">*</span>
+
+<span class="nt">OK</span>
+</pre></div>

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
+```

templates/docs/monitoring_cron_jobs.html

@@ -13,8 +13,8 @@ after a job completes.</p>
 script is presumably a headless, background process. Even if it works
 correctly currently, it can start silently failing in future, without
 anyone noticing.</p>
-<p>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.</p>
+<p>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.</p>
 <ol>
 <li>
 <p>If you have not already, sign up for a free SITE_NAME account.</p>

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.
 

templates/front/base_docs.html

@@ -13,11 +13,9 @@
         </li>
         {% 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" %}
 
         <li class="nav-header">Pinging Examples</li>
+        {% 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" %}
 
+        <li class="nav-header">Guides</li>
+        {% 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" %}
+
         <li class="nav-header">Developer Tools</li>
         <li{% if section == "api" %} class="active"{% endif %}>
-            <a href="{% url 'hc-docs-api' %}">API</a>
+            <a href="{% url 'hc-docs-api' %}">Management API</a>
         </li>
         {% include "front/docs_nav_item.html" with slug="resources" title="Third-party resources" %}