healthchecks/templates/front/docs_api.html

{% extends "front/base_docs.html" %}
{% load compress staticfiles hc_extras %}

{% block title %}REST API - {% site_name %}{% 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/&lt;code&gt;</code>
        </td>
    </tr>
    <tr>
        <td><a href="#pause-check">Pause monitoring of a check</a></td>
        <td>
            <code>POST {{ SITE_ROOT }}/api/v1/checks/&lt;code&gt;/pause</code>
        </td>
    </tr>
    <tr>
        <td><a href="#delete-check">Delete check</a></td>
        <td>
            <code>DELETE {{ SITE_ROOT }}/api/v1/checks/&lt;code&gt;</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=&lt;value&gt;</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&amp;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/&lt;code&gt;</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/&lt;uuid&gt;/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/&lt;uuid&gt;</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 %}