You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
166 lines
4.8 KiB
166 lines
4.8 KiB
{% 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 API calls to:
|
|
</p>
|
|
<ul>
|
|
<li><a href="#list-checks">List existing checks</a></li>
|
|
<li><a href="#create-check">Create a new check</a></li>
|
|
<li><a href="#pause-check">Pause monitoring of a check</a></li>
|
|
</ul>
|
|
|
|
<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 client can authenticate itself by sending an appropriate HTTP
|
|
request header. The header's name should be <code>X-Api-Key</code> and
|
|
its value should be your API key.
|
|
</p>
|
|
|
|
<p> Alternatively, for POST requests with a JSON request body,
|
|
the client can include an <code>api_key</code> field in the JSON document.
|
|
See below the "Create a check" section for an example.
|
|
</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>
|
|
|
|
<!-- ********************************************************************** /-->
|
|
|
|
<a class="section" name="list-checks">
|
|
<h2 class="rule">List checks</h2>
|
|
</a>
|
|
|
|
<div class="api-path">GET {{ SITE_ROOT }}/api/v1/checks/</div>
|
|
|
|
<p>
|
|
Returns a list of checks. This API call takes no parameters and returns
|
|
a JSON document with all checks in user's account.
|
|
</p>
|
|
<h3 class="api-section">Example Request</h3>
|
|
{% include "front/snippets/list_checks_request.html" %}
|
|
|
|
<h3 class="api-section">Example Response</h3>
|
|
{% include "front/snippets/list_checks_response.html" %}
|
|
|
|
<!-- ********************************************************************** /-->
|
|
|
|
<a class="section" name="create-check">
|
|
<h2 class="rule">Create a check</h2>
|
|
</a>
|
|
|
|
<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 space-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>
|
|
{% include "front/snippets/create_check_request.html" %}
|
|
|
|
<h3 class="api-section">Example Response</h3>
|
|
{% include "front/snippets/create_check_response.html" %}
|
|
|
|
|
|
<!-- ********************************************************************** /-->
|
|
|
|
|
|
<a class="section" name="pause-check">
|
|
<h2 class="rule">Pause Monitoring of a Check</h2>
|
|
</a>
|
|
|
|
<div class="api-path">POST {{ SITE_ROOT }}/api/v1/checks/<uuid>/pause</div>
|
|
|
|
<strong></strong>
|
|
|
|
<p>
|
|
Disables monitoring for a check, without removing it. The check goes
|
|
into a "paused" state. You can resume monitoring of the check by pinging
|
|
it.
|
|
</p>
|
|
<p>
|
|
This API call has no request parameters.
|
|
</p>
|
|
|
|
<h3 class="api-section">Example Request</h3>
|
|
{% include "front/snippets/pause_check_request.html" %}
|
|
|
|
<h3 class="api-section">Example Response</h3>
|
|
{% include "front/snippets/pause_check_response.html" %}
|
|
|
|
|
|
{% endblock %}
|