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

Update API docs.

Browse Source
This commit is contained in:
Pēteris Caune 2020-06-15 13:25:55 +03:00
parent 832580f343
commit c3d8ee0965
No known key found for this signature in database
GPG Key ID: E28D7679E9A9EDE2
2 changed files with 100 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
templates/docs/api.html
View File

@ -43,6 +43,10 @@ checks in user's account.</p>
<td><code>GET SITE_ROOT/api/v1/checks/&lt;uuid&gt;/pings/</code></td>
</tr>
<tr>
<td><a href="#list-flips">Get a list of check's status changes</a></td>
<td><code>GET SITE_ROOT/api/v1/checks/&lt;uuid&gt;/flips/</code></td>
</tr>
<tr>
<td><a href="#list-channels">Get a list of existing integrations</a></td>
<td><code>GET SITE_ROOT/api/v1/channels/</code></td>
</tr>
@ -679,6 +683,69 @@ number of returned pings depends on account's billing plan: 100 for free account
</code></pre></div>
<h2 class="rule" id="list-flips">Get a list of check's status changes</h2>
<p><code>GET SITE_ROOT/api/v1/checks/&lt;uuid&gt;/flips/</code><br>
<code>GET SITE_ROOT/api/v1/checks/&lt;unique_key&gt;/flips/</code></p>
<p>Returns a list of "flips" this check has experienced. A flip is a change of status
(from "down" to "up", or from "up" to "down").</p>
<h3>Query String Parameters</h3>
<dl>
<dt>seconds=&lt;value&gt;</dt>
<dd>
<p>Returns the flips from the last <code>value</code> seconds</p>
<p>Example:</p>
<p><code>SITE_ROOT/api/v1/checks/&lt;uuid|unique_key&gt;/flips/?seconds=3600</code></p>
</dd>
<dt>start=&lt;value&gt;</dt>
<dd>
<p>Returns flips that are newer than the specified UNIX timestamp.</p>
<p>Example:</p>
<p><code>SITE_ROOT/api/v1/checks/&lt;uuid|unique_key&gt;/flips/?start=1592214380</code></p>
</dd>
<dt>end=&lt;value&gt;</dt>
<dd>
<p>Returns flips that are older than the specified UNIX timestamp.</p>
<p>Example:</p>
<p><code>SITE_ROOT/api/v1/checks/&lt;uuid|unique_key&gt;/flips/?end=1592217980</code></p>
</dd>
</dl>
<h3>Response Codes</h3>
<dl>
<dt>200 OK</dt>
<dd>The request succeeded.</dd>
<dt>400 Bad Request</dt>
<dd>Invalid query parameters.</dd>
<dt>401 Unauthorized</dt>
<dd>The API key is either missing or invalid.</dd>
<dt>403 Forbidden</dt>
<dd>Access denied, wrong API key.</dd>
<dt>404 Not Found</dt>
<dd>The specified check does not exist.</dd>
</dl>
<h3>Example Request</h3>
<div class="highlight"><pre><span></span><code>curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/flips/ <span class="se">\</span>
--header <span class="s2">&quot;X-Api-Key: your-api-key&quot;</span>
</code></pre></div>
<h3>Example Response</h3>
<div class="highlight"><pre><span></span><code><span class="p">[</span>
<span class="p">{</span>
<span class="nt">&quot;timestamp&quot;</span><span class="p">:</span> <span class="s2">&quot;2020-03-23T10:18:23+00:00&quot;</span><span class="p">,</span>
<span class="nt">&quot;up&quot;</span><span class="p">:</span> <span class="mi">1</span>
<span class="p">},</span>
<span class="p">{</span>
<span class="nt">&quot;timestamp&quot;</span><span class="p">:</span> <span class="s2">&quot;2020-03-23T10:17:15+00:00&quot;</span><span class="p">,</span>
<span class="nt">&quot;up&quot;</span><span class="p">:</span> <span class="mi">0</span>
<span class="p">},</span>
<span class="p">{</span>
<span class="nt">&quot;timestamp&quot;</span><span class="p">:</span> <span class="s2">&quot;2020-03-23T10:16:18+00:00&quot;</span><span class="p">,</span>
<span class="nt">&quot;up&quot;</span><span class="p">:</span> <span class="mi">1</span>
<span class="p">}</span>
<span class="p">]</span>
</code></pre></div>
<h2 class="rule" id="list-channels">Get a List of Existing Integrations</h2>
<p><code>GET SITE_ROOT/api/v1/channels/</code></p>
<p>Returns a list of integrations belonging to the project.</p>

67
templates/docs/api.md
View File

@ -14,7 +14,8 @@ Endpoint Name | Endpoint Address
[Update an existing check](#update-check) | `POST SITE_ROOT/api/v1/checks/<uuid>`
[Pause monitoring of a check](#pause-check) | `POST SITE_ROOT/api/v1/checks/<uuid>/pause`
[Delete check](#delete-check) | `DELETE SITE_ROOT/api/v1/checks/<uuid>`
[Get a list of check's logged pings](#list-pings) | `GET SITE_ROOT/api/v1/checks/<uuid>/pings/`
[Get a list of check's logged pings](#list-pings) | `GET SITE_ROOT/api/v1/checks/<uuid>/pings/`
[Get a list of check's status changes](#list-flips) | `GET SITE_ROOT/api/v1/checks/<uuid>/flips/`
[Get a list of existing integrations](#list-channels) | `GET SITE_ROOT/api/v1/channels/`
## Authentication
@ -746,33 +747,36 @@ curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pings/ \
```
## Get a list of check's flips {: #list-flips .rule }
## Get a list of check's status changes {: #list-flips .rule }
`GET SITE_ROOT/api/v1/checks/<uuid>/flips/` or `GET SITE_ROOT/api/v1/checks/<unique_key>/flips/`
`GET SITE_ROOT/api/v1/checks/<uuid>/flips/`<br>
`GET SITE_ROOT/api/v1/checks/<unique_key>/flips/`
Returns a list of flips this check has experienced. A flip is a change of status (up, or down).
This endpoint returns the status of a check for the period of time passed according to the below parameters. If no parameters are passed, the default is to return flips occuring in the previous 3600 seconds (`/?seconds=3600`), which is the last hour.
Returns a list of "flips" this check has experienced. A flip is a change of status
(from "down" to "up", or from "up" to "down").
### Query String Parameters
Either the seconds or the start (and end) parameters can be passed. Passing both the seconds parameter and the start/end parameters will return a 400 error (see below).
seconds=&lt;value&gt;
: Filters the checks, and returns the flip history in the last `n` seconds
: Returns the flips from the last `value` seconds
Example:
`SITE_ROOT/api/v1/checks/<uuid|unique_key>/flips/?seconds=3600`
start=&lt;value&gt;&amp;end=&lt;value&gt
: Filters the checks, and returns the flip history between the start and end timestamps.
If provided, both values must be unix timestamps. The `end` parameter is optional and defaults to the timestamp of the current date and time.
start=&lt;value&gt;
: Returns flips that are newer than the specified UNIX timestamp.
Example:
`SITE_ROOT/api/v1/checks/<uuid|unique_key>/flips/?seconds=3600`
`SITE_ROOT/api/v1/checks/<uuid|unique_key>/flips/?start=1592214380`
end=&lt;value&gt;
: Returns flips that are older than the specified UNIX timestamp.
Example:
`SITE_ROOT/api/v1/checks/<uuid|unique_key>/flips/?end=1592217980`
### Response Codes
@ -781,7 +785,7 @@ start=&lt;value&gt;&amp;end=&lt;value&gt
: The request succeeded.
400 Bad Request
: Both a seconds and a start or end query string parameter has been passed, which is unsupported.
: Invalid query parameters.
401 Unauthorized
: The API key is either missing or invalid.
@ -802,25 +806,20 @@ curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/flips/ \
### Example Response
```json
{
"name": "My First Check",
"tags": "",
"desc": "",
"grace": 3600,
"n_pings": 2,
"status": "up",
"last_ping": "2020-06-12T02:18:46+00:00",
"next_ping": "2020-06-13T02:18:46+00:00",
"manual_resume": false,
"history": [
{
"timestamp": "2020-03-23T23:30:18.767Z",
"up": 1
}
],
"unique_key": "e855898bebff1756cde7c571319d877d07a38dab",
"timeout": 86400
}
[
{
"timestamp": "2020-03-23T10:18:23+00:00",
"up": 1
},
{
"timestamp": "2020-03-23T10:17:15+00:00",
"up": 0
},
{
"timestamp": "2020-03-23T10:16:18+00:00",
"up": 1
}
]
```
## Get a List of Existing Integrations {: #list-channels .rule }