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.
427 lines
13 KiB
427 lines
13 KiB
{% extends "front/base_docs.html" %}
|
|
{% load compress staticfiles hc_extras %}
|
|
|
|
{% block title %}REST API - {% site_name %}{% endblock %}
|
|
|
|
{% block description %}
|
|
<meta name="description" content="Build advanced integrations and custom dashboards using {% site_name %} REST API calls.">
|
|
{% endblock %}
|
|
|
|
{% block docs_content %}
|
|
|
|
<h2>REST API</h2>
|
|
<p>{% site_name %} REST API supports listing, creating,
|
|
updating, pausing and deleting checks in user's account.
|
|
</p>
|
|
|
|
<h2>API Endpoints</h2>
|
|
<table class="table table-bordered">
|
|
<tr>
|
|
<td><a href="#list-checks">Get list of existing checks</a></td>
|
|
<td>
|
|
<code>GET {{ SITE_ROOT }}/api/v1/checks/</code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#create-check">Create a new check</a></td>
|
|
<td>
|
|
<code>POST {{ SITE_ROOT }}/api/v1/checks/</code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#update-check">Update an existing check</a></td>
|
|
<td>
|
|
<code>POST {{ SITE_ROOT }}/api/v1/checks/<code></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#pause-check">Pause monitoring of a check</a></td>
|
|
<td>
|
|
<code>POST {{ SITE_ROOT }}/api/v1/checks/<code>/pause</code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#delete-check">Delete check</a></td>
|
|
<td>
|
|
<code>DELETE {{ SITE_ROOT }}/api/v1/checks/<code></code>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h2>Authentication</h2>
|
|
<p>Your requests to {% site_name %} REST API must authenticate using an
|
|
API key. By default, an user account on {% site_name %} 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>API Requests</h2>
|
|
|
|
<p>
|
|
For POST requests, the {% site_name %} API expects request body to be
|
|
a JSON document (<em>not</em> a <code>multipart/form-data</code> encoded
|
|
form data).
|
|
</p>
|
|
|
|
<h2>API Responses</h2>
|
|
|
|
<p>
|
|
{% site_name %} 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">Get List of Existing Checks</h2>
|
|
</a>
|
|
|
|
<div class="api-path">GET {{ SITE_ROOT }}/api/v1/checks/</div>
|
|
|
|
<p>Returns a list of checks belonging to the user, optionally filtered by
|
|
one or more tags.</p>
|
|
|
|
<h3 class="api-section">Query String Parameters</h3>
|
|
<table class="table">
|
|
<tr>
|
|
<th>tag=<value></th>
|
|
<td>
|
|
<p>
|
|
Filters the checks, and returns only the checks that
|
|
are tagged with the specified value.
|
|
</p>
|
|
<p>
|
|
This parameter can be repeated multiple times.
|
|
</p>
|
|
<p>Example:</p>
|
|
<pre>{{ SITE_ROOT }}/api/v1/checks/?tag=foo&tag=bar</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<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>
|
|
|
|
<p>This API call can be used to create both "simple" and "cron" checks.
|
|
To create a "simple" check, specify the "timeout" parameter.
|
|
To create a "cron" check, specify the "schedule" and "tz" parameters.
|
|
</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>
|
|
<p>Example:</p>
|
|
<pre>{"tags": "reports staging"}</pre>
|
|
</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: 2592000 (30 days).</p>
|
|
<p>Example for 5 minute timeout:</p>
|
|
<pre>{"kind": "simple", "timeout": 300}</pre>
|
|
</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: 2592000 (30 days).</p>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<th>schedule</th>
|
|
<td>
|
|
<p>string, optional, default value: "* * * * *".</p>
|
|
<p>A cron expression defining this check's schedule.</p>
|
|
<p>If you specify both "timeout" and "schedule" parameters,
|
|
"timeout" will be ignored and "schedule" will be used.</p>
|
|
<p>Example for a check running every half-hour:</p>
|
|
<pre>{"schedule": "0,30 * * * *"}</pre>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<th>tz</th>
|
|
<td>
|
|
<p>string, optional, default value: "UTC".</p>
|
|
<p>Server's timezone. This setting only has effect in combination
|
|
with the "schedule" paremeter.</p>
|
|
<p>Example:</p>
|
|
<pre>{"tz": "Europe/Riga"}</pre>
|
|
</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>
|
|
<tr>
|
|
<th>unique</th>
|
|
<td>
|
|
<p>array of string values, optional, default value: [].</p>
|
|
<p>Before creating a check, look for existing checks, filtered
|
|
by fields listed in <code>unique</code>. If a matching check is
|
|
found, return it with HTTP status code 200. If no matching check is
|
|
found, proceed as normal: create a check and return it
|
|
with HTTP status code 201.</p>
|
|
|
|
<p>The accepted values are: <code>name</code>,
|
|
<code>tags</code>, <code>timeout</code> and <code>grace</code>.</p>
|
|
|
|
<p>Example:</p>
|
|
<pre>{"name": "Backups", unique: ["name"]}</pre>
|
|
<p>In this example, if a check named "Backups" exists, it will
|
|
be returned. Otherwise, a new check will be created and
|
|
returned.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h3 class="api-section">Response Codes</h3>
|
|
<table class="table">
|
|
<tr>
|
|
<th>201 Created</th>
|
|
<td>Returned if the check was successfully created.</td>
|
|
</tr>
|
|
<tr>
|
|
<th>200 OK</th>
|
|
<td>Returned if the <code>unique</code> parameter was used and an
|
|
existing check was matched.</td>
|
|
</tr>
|
|
<tr>
|
|
<th>403 Forbidden</th>
|
|
<td>Returned if the account's check limit has been reached.
|
|
For free accounts, the limit is 20 checks per account.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h3 class="api-section">Example Request</h3>
|
|
{% include "front/snippets/create_check_request_a.html" %}
|
|
<br>
|
|
<p>Or, alternatively:</p>
|
|
{% include "front/snippets/create_check_request_b.html" %}
|
|
|
|
|
|
<h3 class="api-section">Example Response</h3>
|
|
{% include "front/snippets/create_check_response.html" %}
|
|
|
|
<!-- ********************************************************************** /-->
|
|
|
|
<a class="section" name="update-check">
|
|
<h2 class="rule">Update an Existing Check</h2>
|
|
</a>
|
|
|
|
<div class="api-path">POST {{ SITE_ROOT }}/api/v1/checks/<code></div>
|
|
|
|
<strong></strong>
|
|
|
|
<p>
|
|
Updates an existing check. All request parameters are optional. The
|
|
check is updated only with the supplied request parameters.
|
|
If any parameter is omitted, its value is left unchanged.
|
|
</p>
|
|
|
|
<h3 class="api-section">Request Parameters</h3>
|
|
<table class="table">
|
|
<tr>
|
|
<th>name</th>
|
|
<td>
|
|
<p>string, optional.</p>
|
|
<p>Name for the check.</p>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<th>tags</th>
|
|
<td>
|
|
<p>string, optional.</p>
|
|
<p>A space-delimited list of tags for the check.</p>
|
|
<p>Example:</p>
|
|
<pre>{"tags": "reports staging"}</pre>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<th>timeout</th>
|
|
<td>
|
|
<p>number, optional.</p>
|
|
<p>A number of seconds, the expected period of this check.</p>
|
|
<p>Minimum: 60 (one minute), maximum: 2592000 (30 days).</p>
|
|
<p>Example for 5 minute timeout:</p>
|
|
<pre>{"kind": "simple", "timeout": 300}</pre>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<th>grace</th>
|
|
<td>
|
|
<p>number, optional.</p>
|
|
<p>A number of seconds, the grace period for this check.</p>
|
|
<p>Minimum: 60 (one minute), maximum: 2592000 (30 days).</p>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<th>schedule</th>
|
|
<td>
|
|
<p>string, optional.</p>
|
|
<p>A cron expression defining this check's schedule.</p>
|
|
<p>If you specify both "timeout" and "schedule" parameters,
|
|
"timeout" will be ignored and "schedule" will be used.</p>
|
|
<p>Example for a check running every half-hour:</p>
|
|
<pre>{"schedule": "0,30 * * * *"}</pre>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<th>tz</th>
|
|
<td>
|
|
<p>string, optional.</p>
|
|
<p>Server's timezone. This setting only has effect in combination
|
|
with the "schedule" paremeter.</p>
|
|
<p>Example:</p>
|
|
<pre>{"tz": "Europe/Riga"}</pre>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<th>channels</th>
|
|
<td>
|
|
<p>string, optional.</p>
|
|
<p>Set this field to a special value "*"
|
|
to automatically assign all existing notification channels.
|
|
</p>
|
|
<p>Set this field to a special value "" (empty string)
|
|
to automatically <em>unassign</em> all notification channels.
|
|
</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h3 class="api-section">Response Codes</h3>
|
|
<table class="table">
|
|
<tr>
|
|
<th>200 OK</th>
|
|
<td>Returned if the check was successfully updated.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h3 class="api-section">Example Request</h3>
|
|
{% include "front/snippets/update_check_request_a.html" %}
|
|
<br>
|
|
<p>Or, alternatively:</p>
|
|
{% include "front/snippets/update_check_request_b.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>
|
|
|
|
<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" %}
|
|
|
|
<p>Note: the <code>--data ""</code> argument forces curl to send a
|
|
<code>Content-Length</code> request header even though the request body
|
|
is empty. For HTTP POST requests, the <code>Content-Length</code> header
|
|
is sometimes required by some network proxies and web servers.
|
|
</p>
|
|
|
|
<h3 class="api-section">Example Response</h3>
|
|
{% include "front/snippets/pause_check_response.html" %}
|
|
|
|
<!-- ********************************************************************** /-->
|
|
|
|
<a class="section" name="delete-check">
|
|
<h2 class="rule">Delete Check</h2>
|
|
</a>
|
|
|
|
<div class="api-path">DELETE {{ SITE_ROOT }}/api/v1/checks/<uuid></div>
|
|
|
|
<p>
|
|
Permanently deletes the check from user's account. Returns JSON
|
|
representation of the check that was just deleted.
|
|
</p>
|
|
<p>
|
|
This API call has no request parameters.
|
|
</p>
|
|
|
|
<h3 class="api-section">Example Request</h3>
|
|
|
|
{% include "front/snippets/delete_check_request.html" %}
|
|
|
|
<h3 class="api-section">Example Response</h3>
|
|
{% include "front/snippets/create_check_response.html" %}
|
|
|
|
{% endblock %}
|
|
|
|
{% block scripts %}
|
|
{% compress js %}
|
|
<script src="{% static 'js/jquery-2.1.4.min.js' %}"></script>
|
|
<script src="{% static 'js/bootstrap.min.js' %}"></script>
|
|
<script src="{% static 'js/clipboard.min.js' %}"></script>
|
|
<script src="{% static 'js/snippet-copy.js' %}"></script>
|
|
{% endcompress %}
|
|
{% endblock %}
|