Browse Source

Improve TOC and section titles in Management API docs

pull/761/head
Pēteris Caune 2 months ago
parent
commit
dbb360e524
No known key found for this signature in database GPG Key ID: E28D7679E9A9EDE2
  1. 52
      templates/docs/api.html
  2. 37
      templates/docs/api.md

52
templates/docs/api.html

@ -11,7 +11,11 @@ in your account.</p>
</thead>
<tbody>
<tr>
<td><a href="#list-checks">Get a list of existing checks</a></td>
<td><strong>Checks</strong></td>
<td></td>
</tr>
<tr>
<td><a href="#list-checks">List existing checks</a></td>
<td><code>GET SITE_ROOT/api/v1/checks/</code></td>
</tr>
<tr>
@ -39,7 +43,11 @@ in your account.</p>
<td><code>DELETE SITE_ROOT/api/v1/checks/&lt;uuid&gt;</code></td>
</tr>
<tr>
<td><a href="#list-pings">Get a list of check's logged pings</a></td>
<td><strong>Pings</strong></td>
<td></td>
</tr>
<tr>
<td><a href="#list-pings">List check's logged pings</a></td>
<td><code>GET SITE_ROOT/api/v1/checks/&lt;uuid&gt;/pings/</code></td>
</tr>
<tr>
@ -47,15 +55,27 @@ in your account.</p>
<td><code>GET SITE_ROOT/api/v1/checks/&lt;uuid&gt;/pings/&lt;n&gt;/body</code></td>
</tr>
<tr>
<td><a href="#list-flips">Get a list of check's status changes</a></td>
<td><strong>Flips</strong></td>
<td></td>
</tr>
<tr>
<td><a href="#list-flips">List check's status changes</a></td>
<td><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></td>
</tr>
<tr>
<td><a href="#list-channels">Get a list of existing integrations</a></td>
<td><strong>Integrations</strong></td>
<td></td>
</tr>
<tr>
<td><a href="#list-channels">List existing integrations</a></td>
<td><code>GET SITE_ROOT/api/v1/channels/</code></td>
</tr>
<tr>
<td><a href="#list-badges">Get project's badges</a></td>
<td><strong>Badges</strong></td>
<td></td>
</tr>
<tr>
<td><a href="#list-badges">List project's badges</a></td>
<td><code>GET SITE_ROOT/api/v1/badges/</code></td>
</tr>
</tbody>
@ -72,10 +92,10 @@ and read-only API keys on the <strong>Project Settings</strong> page.</p>
<dd>
<p>Only works with the following API endpoints:</p>
<ul>
<li><a href="#list-checks">Get a list of existing checks</a></li>
<li><a href="#list-checks">List existing checks</a></li>
<li><a href="#get-check">Get a single check</a></li>
<li><a href="#list-flips">Get a list of check's status changes</a></li>
<li><a href="#list-badges">Get project's badges</a></li>
<li><a href="#list-flips">List check's status changes</a></li>
<li><a href="#list-badges">List project's badges</a></li>
</ul>
<p>Omits sensitive information from the API responses. See the documentation of
individual API endpoints for details.</p>
@ -93,7 +113,7 @@ a JSON document (<em>not</em> a <code>multipart/form-data</code> encoded form da
In general, 2xx class indicates success, 4xx indicates a client error,
and 5xx indicates a server error.</p>
<p>The response may contain a JSON document with additional data.</p>
<h2 class="rule" id="list-checks">Get a List of Existing Checks</h2>
<h2 class="rule" id="list-checks">List Existing Checks</h2>
<p><code>GET SITE_ROOT/api/v1/checks/</code></p>
<p>Returns a list of checks belonging to the user, optionally filtered by
one or more tags.</p>
@ -179,7 +199,7 @@ and <code>paused</code>.</p>
<code>ping_url</code>, <code>update_url</code>, <code>pause_url</code>, <code>resume_url</code>, <code>channels</code>. It adds an extra
<code>unique_key</code> field. The <code>unique_key</code> identifier is stable across API calls, and
you can use it in the <a href="#get-check">Get a single check</a>
and <a href="#list-flips">Get a list of check's status changes</a> API calls.</p>
and <a href="#list-flips">List check's status changes</a> API calls.</p>
<p>Example:</p>
<div class="highlight"><pre><span></span><code><span class="p">{</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;checks&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"></span>
@ -394,7 +414,7 @@ integrations. Example:</p>
<p><pre>{"channels": "*"}</pre></p>
<p>To assign specific integrations, use a comma-separated list of integration
UUIDs. You can look up integration UUIDs using the
<a href="#list-channels">Get a List of Existing Integrations</a> API call.</p>
<a href="#list-channels">List Existing Integrations</a> API call.</p>
<p>Example:</p>
<p><pre>{"channels":
"4ec5a071-2d08-4baa-898a-eb4eb3cd6941,746a083e-f542-4554-be1a-707ce16d3acc"}</pre></p>
@ -629,7 +649,7 @@ all existing integrations. Example:</p>
<p><pre>{"channels": ""}</pre></p>
<p>To assign specific integrations, use a comma-separated list of integration
UUIDs. You can look up integration UUIDs using the
<a href="#list-channels">Get a List of Existing Integrations</a> API call.</p>
<a href="#list-channels">List Existing Integrations</a> API call.</p>
<p>Example:</p>
<p><pre>{"channels":
"4ec5a071-2d08-4baa-898a-eb4eb3cd6941,746a083e-f542-4554-be1a-707ce16d3acc"}</pre></p>
@ -915,7 +935,7 @@ check that was just deleted.</p>
<span class="p">}</span><span class="w"></span>
</code></pre></div>
<h2 class="rule" id="list-pings">Get a list of check's logged pings</h2>
<h2 class="rule" id="list-pings">List check's logged pings</h2>
<p><code>GET SITE_ROOT/api/v1/checks/&lt;uuid&gt;/pings/</code></p>
<p>Returns a list of pings this check has received.</p>
<p>This endpoint returns pings in reverse order (most recent first), and the total
@ -1008,7 +1028,7 @@ response header, and the ping body is returned verbatim in the response body.</p
--header <span class="s2">&quot;X-Api-Key: your-api-key&quot;</span>
</code></pre></div>
<h2 class="rule" id="list-flips">Get a list of check's status changes</h2>
<h2 class="rule" id="list-flips">List 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
@ -1069,7 +1089,7 @@ response header, and the ping body is returned verbatim in the response body.</p
<span class="p">]</span><span class="w"></span>
</code></pre></div>
<h2 class="rule" id="list-channels">Get a List of Existing Integrations</h2>
<h2 class="rule" id="list-channels">List Existing Integrations</h2>
<p><code>GET SITE_ROOT/api/v1/channels/</code></p>
<p>Returns a list of integrations belonging to the project.</p>
<h3>Response Codes</h3>
@ -1100,7 +1120,7 @@ response header, and the ping body is returned verbatim in the response body.</p
<span class="p">}</span><span class="w"></span>
</code></pre></div>
<h2 class="rule" id="list-badges">Get Project's Badges</h2>
<h2 class="rule" id="list-badges">List Project's Badges</h2>
<p><code>GET SITE_ROOT/api/v1/badges/</code></p>
<p>Returns a map of all tags in the project, with badge URLs for each tag. SITE_NAME
provides badges in a few different formats:</p>

37
templates/docs/api.md

@ -7,18 +7,23 @@ in your account.
Endpoint Name | Endpoint Address
------------------------------------------------------|-------
[Get a list of existing checks](#list-checks) | `GET SITE_ROOT/api/v1/checks/`
**Checks**|
[List existing checks](#list-checks) | `GET SITE_ROOT/api/v1/checks/`
[Get a single check](#get-check) | `GET SITE_ROOT/api/v1/checks/<uuid>`<br>`GET SITE_ROOT/api/v1/checks/<unique_key>`
[Create a new check](#create-check) | `POST SITE_ROOT/api/v1/checks/`
[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`
[Resume monitoring of a check](#resume-check) | `POST SITE_ROOT/api/v1/checks/<uuid>/resume`
[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/`
**Pings**|
[List check's logged pings](#list-pings) | `GET SITE_ROOT/api/v1/checks/<uuid>/pings/`
[Get a ping's logged body](#ping-body) | `GET SITE_ROOT/api/v1/checks/<uuid>/pings/<n>/body`
[Get a list of check's status changes](#list-flips) | `GET SITE_ROOT/api/v1/checks/<uuid>/flips/`<br>`GET SITE_ROOT/api/v1/checks/<unique_key>/flips/`
[Get a list of existing integrations](#list-channels) | `GET SITE_ROOT/api/v1/channels/`
[Get project's badges](#list-badges) | `GET SITE_ROOT/api/v1/badges/`
**Flips**|
[List check's status changes](#list-flips) | `GET SITE_ROOT/api/v1/checks/<uuid>/flips/`<br>`GET SITE_ROOT/api/v1/checks/<unique_key>/flips/`
**Integrations**|
[List existing integrations](#list-channels) | `GET SITE_ROOT/api/v1/channels/`
**Badges**|
[List project's badges](#list-badges) | `GET SITE_ROOT/api/v1/badges/`
## Authentication
@ -33,10 +38,10 @@ read-write key
read-only key
: Only works with the following API endpoints:
* [Get a list of existing checks](#list-checks)
* [List existing checks](#list-checks)
* [Get a single check](#get-check)
* [Get a list of check's status changes](#list-flips)
* [Get project's badges](#list-badges)
* [List check's status changes](#list-flips)
* [List project's badges](#list-badges)
Omits sensitive information from the API responses. See the documentation of
individual API endpoints for details.
@ -59,7 +64,7 @@ and 5xx indicates a server error.
The response may contain a JSON document with additional data.
## Get a List of Existing Checks {: #list-checks .rule }
## List Existing Checks {: #list-checks .rule }
`GET SITE_ROOT/api/v1/checks/`
@ -155,7 +160,7 @@ When using the read-only API key, SITE_NAME omits the following fields from resp
`ping_url`, `update_url`, `pause_url`, `resume_url`, `channels`. It adds an extra
`unique_key` field. The `unique_key` identifier is stable across API calls, and
you can use it in the [Get a single check](#get-check)
and [Get a list of check's status changes](#list-flips) API calls.
and [List check's status changes](#list-flips) API calls.
Example:
@ -408,7 +413,7 @@ channels
To assign specific integrations, use a comma-separated list of integration
UUIDs. You can look up integration UUIDs using the
[Get a List of Existing Integrations](#list-channels) API call.
[List Existing Integrations](#list-channels) API call.
Example:
@ -703,7 +708,7 @@ channels
To assign specific integrations, use a comma-separated list of integration
UUIDs. You can look up integration UUIDs using the
[Get a List of Existing Integrations](#list-channels) API call.
[List Existing Integrations](#list-channels) API call.
Example:
@ -1059,7 +1064,7 @@ curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc \
}
```
## Get a list of check's logged pings {: #list-pings .rule }
## List check's logged pings {: #list-pings .rule }
`GET SITE_ROOT/api/v1/checks/<uuid>/pings/`
@ -1171,7 +1176,7 @@ curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pings/397/body
--header "X-Api-Key: your-api-key"
```
## Get a list of check's status changes {: #list-flips .rule }
## List check's status changes {: #list-flips .rule }
`GET SITE_ROOT/api/v1/checks/<uuid>/flips/`<br>
`GET SITE_ROOT/api/v1/checks/<unique_key>/flips/`
@ -1246,7 +1251,7 @@ curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/flips/ \
]
```
## Get a List of Existing Integrations {: #list-channels .rule }
## List Existing Integrations {: #list-channels .rule }
`GET SITE_ROOT/api/v1/channels/`
@ -1285,7 +1290,7 @@ curl --header "X-Api-Key: your-api-key" SITE_ROOT/api/v1/channels/
}
```
## Get Project's Badges {: #list-badges .rule }
## List Project's Badges {: #list-badges .rule }
`GET SITE_ROOT/api/v1/badges/`

Loading…
Cancel
Save