harmacist/healthchecks
1
0
Fork 0
forked from GithubBackups/healthchecks
Code Issues Pull Requests Projects Releases Wiki Activity

API documentation.

Browse Source
This commit is contained in:
Pēteris Caune 2016-02-18 00:07:10 +02:00
parent 6efb822f95
commit f78fb95d5e
6 changed files with 210 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
hc/front/urls.py
View File

@ -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"),

16
hc/front/views.py
View File

@ -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"})

40
static/css/docs.css
View File

@ -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;
}

32
templates/front/base_docs.html Normal file
View File

@ -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 %}

13
templates/front/docs.html
View File

@ -1,10 +1,9 @@
{% extends "base.html" %}
{% extends "front/base_docs.html" %}
{% load staticfiles %}
{% block title %}Documentation - healthchecks.io{% endblock %}
{% block content %}
<div class="row"><div class="col-sm-12">
{% block docs_content %}
<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 %}

113
templates/front/docs_api.html Normal file
View File

@ -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 %}