API documentation.

hc/front/urls.py

@@ -12,6 +12,7 @@ urlpatterns = [
     url(r'^checks/([\w-]+)/remove/$',   views.remove_check, name="hc-remove-check"),
     url(r'^checks/([\w-]+)/log/$',      views.log, name="hc-log"),
     url(r'^docs/$',                     views.docs, name="hc-docs"),
+    url(r'^docs/api/$',                 views.docs_api, name="hc-docs-api"),
     url(r'^about/$',                    views.about, name="hc-about"),
     url(r'^privacy/$',                  views.privacy, name="hc-privacy"),
     url(r'^integrations/$',                 views.channels, name="hc-channels"),

hc/front/views.py

@@ -13,7 +13,7 @@ from django.utils.crypto import get_random_string
 from django.utils.six.moves.urllib.parse import urlencode
 from hc.accounts.models import Profile
 from hc.api.decorators import uuid_or_400
-from hc.api.models import Channel, Check, Ping
+from hc.api.models import Channel, Check, Ping, DEFAULT_TIMEOUT, DEFAULT_GRACE
 from hc.front.forms import AddChannelForm, NameTagsForm, TimeoutForm
 
 
@@ -91,6 +91,7 @@ def docs(request):
 
     ctx = {
         "page": "docs",
+        "section": "home",
         "ping_endpoint": settings.PING_ENDPOINT,
         "check": check,
         "ping_url": check.url()
@@ -99,6 +100,19 @@ def docs(request):
     return render(request, "front/docs.html", ctx)
 
 
+def docs_api(request):
+    ctx = {
+        "page": "docs",
+        "section": "api",
+        "SITE_ROOT": settings.SITE_ROOT,
+        "PING_ENDPOINT": settings.PING_ENDPOINT,
+        "default_timeout": int(DEFAULT_TIMEOUT.total_seconds()),
+        "default_grace": int(DEFAULT_GRACE.total_seconds())
+    }
+
+    return render(request, "front/docs_api.html", ctx)
+
+
 def about(request):
     return render(request, "front/about.html", {"page": "about"})
 

static/css/docs.css

@@ -1,4 +1,44 @@
+.docs-nav {
+    margin: 20px 0 0 0;
+    padding: 0;
+    list-style: none;
+}
+
+.docs-nav li a {
+    display: block;
+    padding-bottom: 10px;
+}
+
+.docs-nav li.active > a {
+    font-weight: bold;
+}
+
+
+.docs-nav ul {
+    margin: 0 0 0 20px;
+    padding: 0;
+    list-style: none;
+
+}
+
 .curl-opts th {
     white-space: nowrap;
     font-family: monospace;
+}
+
+h2.rule {
+    border-top: 1px solid #ddd;
+    padding-top: 20px;
+}
+
+h3.api-section {
+    font-size: 14px;
+    font-weight: bold;
+    margin: 20px 0;
+}
+
+.api-path {
+    font-family: monospace;
+    font-weight: bold;
+    margin-bottom: 1em;
 }

templates/front/base_docs.html

@@ -0,0 +1,32 @@
+{% extends "base.html" %}
+{% load staticfiles %}
+
+{% block content %}
+<div class="row">
+    <div class="col-sm-2">
+
+    <ul class="docs-nav">
+        <li {% if section == "home" %} class="active" {% endif %}>
+            <a href="{% url 'hc-docs' %}">Executing a Ping</a>
+            <ul>
+                <li><a href="{% url 'hc-docs' %}#crontab">Crontab</a></li>
+                <li><a href="{% url 'hc-docs' %}#bash">Bash</a></li>
+                <li><a href="{% url 'hc-docs' %}#python">Python</a></li>
+                <li><a href="{% url 'hc-docs' %}#node">Node</a></li>
+                <li><a href="{% url 'hc-docs' %}#php">PHP</a></li>
+                <li><a href="{% url 'hc-docs' %}#browser">Browser</a></li>
+                <li><a href="{% url 'hc-docs' %}#email">Email</a></li>
+            </ul>
+        </li>
+        <li {% if section == "api" %} class="active" {% endif %}>
+            <a href="{% url 'hc-docs-api' %}">REST API</a>
+        </li>
+    </ul>
+
+    </div>
+    <div class="col-sm-10">
+        {% block docs_content %}
+        {% endblock %}
+    </div>
+</div>
+{% endblock %}

templates/front/docs.html

@@ -1,10 +1,9 @@
-{% extends "base.html" %}
+{% extends "front/base_docs.html" %}
 {% load staticfiles %}
 
 {% block title %}Documentation - healthchecks.io{% endblock %}
 
-{% block content %}
+{% block docs_content %}
-<div class="row"><div class="col-sm-12">
 
 <h2>Summary</h2>
 <p>
@@ -35,6 +34,7 @@ short and simple string "OK".</p>
     Here are examples of executing pings from different environments.
 </p>
 
+<a name="crontab"></a>
 <h3>Crontab</h3>
 
 <p>
@@ -99,6 +99,7 @@ task runs. Feel free to adjust the curl options to your liking.
     </tr>
 </table>
 
+<a name="bash"></a>
 <h3>Bash or a shell script</h3>
 
 <p>Both <code>curl</code> and <code>wget</code> examples accomplish the same
@@ -111,16 +112,20 @@ thing: they fire off a HTTP GET method.</p>
 
 {% include "front/snippets/bash.html" %}
 
+<a name="python"></a>
 <h3>Python</h3>
 {% include "front/snippets/python.html" %}
 
+<a name="node"></a>
 <h3>Node</h3>
 {% include "front/snippets/node.html" %}
 
 
+<a name="php"></a>
 <h3>PHP</h3>
 {% include "front/snippets/php.html" %}
 
+<a name="browser"></a>
 <h3>Browser</h3>
 <p>
     healthchecks.io includes <code>Access-Control-Allow-Origin:*</code>
@@ -129,6 +134,7 @@ thing: they fire off a HTTP GET method.</p>
 </p>
 {% include "front/snippets/browser.html" %}
 
+<a name="email"></a>
 <h3>Email</h3>
 <p>
     As an alternative to HTTP/HTTPS requests,
@@ -209,5 +215,4 @@ thing: they fire off a HTTP GET method.</p>
     </tr>
 </table>
 
-</div></div>
 {% endblock %}

templates/front/docs_api.html

@@ -0,0 +1,113 @@
+{% extends "front/base_docs.html" %}
+{% load staticfiles %}
+
+{% block title %}REST API - healthchecks.io{% endblock %}
+
+{% block docs_content %}
+
+<h2>REST API</h2>
+<p>
+This is early days for healtchecks.io REST API. For now, there's just
+one API call: for creating a new check.
+</p>
+
+<h2 class="rule">Authentication</h2>
+<p>Your requests to healtchecks.io REST API must authenticate using an
+API key. By default, an user account on healthchecks.io doesn't have
+an API key. You can create one in the <a href="{% url 'hc-profile' %}">Settings</a> page.
+</p>
+
+<p>
+The API uses a simple authentication scheme: the API key should be
+included in the request body (a JSON document) along other fields.
+</p>
+
+<h2 class="rule">API Requests</h2>
+
+<p>
+For POST requests, the healthchecks.io API expects request body to be
+a JSON document (<em>not</em> a <code>mulitpart/form-data</code> encoded
+form data).
+</p>
+
+<h2 class="rule">API Responses</h2>
+
+<p>
+healthchecks.io uses HTTP status codes wherever possible.
+In general, 2xx class indicates success, 4xx indicates an client error,
+and 5xx indicates a server error.
+</p>
+
+<p>
+The response may contain a JSON document with additional data.
+</p>
+
+<h2 class="rule">Create a check</h2>
+
+<div class="api-path">POST {{ SITE_ROOT }}/api/v1/checks/</div>
+
+<strong></strong>
+
+<p>
+    Creates a new check and returns its ping URL.
+    All request parameters are optional and will use their default
+    values if omitted.
+</p>
+
+<h3 class="api-section">Request Parameters</h3>
+<table class="table">
+    <tr>
+        <th>name</th>
+        <td>
+            <p>string, optional, default value: ""</p>
+            <p>Name for the new check.</p>
+        </td>
+    </tr>
+    <tr>
+        <th>tags</th>
+        <td>
+            <p>string, optional, default value: ""</p>
+            <p>A comma-delimited list of tags for the new check.</p>
+        </td>
+    </tr>
+    <tr>
+        <th>timeout</th>
+        <td>
+            <p>number, optional, default value: {{ default_timeout }}.</p>
+            <p>A number of seconds, the expected period of this check.</p>
+            <p>Minimum: 60 (one minute), maximum: 604800 (one week).</p>
+        </td>
+    </tr>
+    <tr>
+        <th>grace</th>
+        <td>
+            <p>number, optional, default value: {{ default_grace }}.</p>
+            <p>A number of seconds, the grace period for this check.</p>
+            <p>Minimum: 60 (one minute), maximum: 604800 (one week).</p>
+        </td>
+    </tr>
+    <tr>
+        <th>channels</th>
+        <td>
+            <p>string, optional, default value: ""</p>
+            <p>By default, if a check is created through API, no notification
+            channels are assigned to it. So, when the check goes up or down,
+            no notifications would be sent. Set this field to a special value "*"
+            to automatically assign all existing notification channels.</p>
+        </td>
+    </tr>
+</table>
+
+<h3 class="api-section">Example Request</h3>
+<pre>
+curl {{ SITE_ROOT }}/v1/checks/ \
+    -X POST \
+    -d '{"name": "Nightly Backups", "tags": "production,www", "timeout": 3600, "grace": 60}'
+</pre>
+
+<h3 class="api-section">Example Response</h3>
+<pre>
+{"ping_url": "{{ PING_ENDPOINT }}20f2d3d0-efe4-4cc1-a114-a186a225de50"}
+</pre>
+
+{% endblock %}