nielsperetzke
/
healthchecks
1
0
Fork 0
Code Issues 0 Pull Requests 0 Projects 0 Releases 32 Wiki Activity
Browse Source

Grammar and style fixes.

pull/426/head
Pēteris Caune 4 years ago
parent
b4729cdb57
commit
c13f65e118
No known key found for this signature in database GPG Key ID: E28D7679E9A9EDE2
5 changed files with 116 additions and 95 deletions
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. +8
    -2
      hc/api/tests/test_create_check.py
  2. +45
    -38
      templates/docs/api.html
  3. +47
    -39
      templates/docs/api.md
  4. +8
    -8
      templates/docs/http_api.html
  5. +8
    -8
      templates/docs/http_api.md

+ 8
- 2
hc/api/tests/test_create_check.py View File

@ -93,9 +93,11 @@ class CreateCheckTestCase(BaseTestCase):
self.assertFalse(Check.objects.exists())
def test_it_supports_unique(self):
Check.objects.create(project=self.project, name="Foo")
check = Check.objects.create(project=self.project, name="Foo")
r = self.post({"api_key": "X" * 32, "name": "Foo", "unique": ["name"]})
r = self.post(
{"api_key": "X" * 32, "name": "Foo", "tags": "bar", "unique": ["name"]}
)
# Expect 200 instead of 201
self.assertEqual(r.status_code, 200)
@ -103,6 +105,10 @@ class CreateCheckTestCase(BaseTestCase):
# And there should be only one check in the database:
self.assertEqual(Check.objects.count(), 1)
# The tags field should have a value now:
check.refresh_from_db()
self.assertEqual(check.tags, "bar")
def test_it_handles_missing_request_body(self):
r = self.client.post(self.URL, content_type="application/json")
self.assertEqual(r.status_code, 401)


+ 45
- 38
templates/docs/api.html View File

@ -1,6 +1,6 @@
<h1>Management API</h1>
<p>SITE_NAME Management API supports listing, creating, updating, pausing and deleting
checks in user's account.</p>
<p>With the Management API, you can programmatically manage checks and integrations
in your account.</p>
<h2>API Endpoints</h2>
<table>
<thead>
@ -50,7 +50,7 @@ checks in user's account.</p>
</table>
<h2>Authentication</h2>
<p>Your requests to SITE_NAME Management API must authenticate using an
API key. API keys are project-specific, there are no account-wide API keys.
API key. All API keys are project-specific. There are no account-wide API keys.
By default, a project on SITE_NAME doesn't have an API key. You can create read-write
and read-only API keys in the <strong>Project Settings</strong> page.</p>
<dl>
@ -69,15 +69,15 @@ individual API endpoints for details.</p>
</dd>
</dl>
<p>The client can authenticate itself by including an <code>X-Api-Key: &lt;your-api-key&gt;</code>
header in a HTTP request. Alternatively, for POST requests with a JSON request body,
the client can include an <code>api_key</code> field in the JSON document.
header in an HTTP request. Alternatively, for POST requests with a JSON request body,
the client can put an <code>api_key</code> field in the JSON document.
See the <a href="#create-check">Create a new check</a> section for an example.</p>
<h2>API Requests</h2>
<p>For POST requests, the SITE_NAME API expects request body to be
<p>For POST requests, the SITE_NAME API expects the 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,
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>
@ -148,9 +148,12 @@ specified value.</p>
</code></pre></div>
<p>When using the read-only API key, the following fields are omitted:
<code>ping_url</code>, <code>update_url</code>, <code>pause_url</code>, <code>channels</code>. An extra <code>unique_key</code> field
is added which can be used <a href="#get-check">to <code>GET</code> a check</a> in place of the <code>UUID</code>. The <code>unique_key</code> identifier is stable across API calls. Example:</p>
<p>When using the read-only API key, SITE_NAME omits the following fields from responses:
<code>ping_url</code>, <code>update_url</code>, <code>pause_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>
<p>Example:</p>
<div class="json highlight"><pre><span></span><code><span class="p">{</span>
<span class="nt">&quot;checks&quot;</span><span class="p">:</span> <span class="p">[</span>
<span class="p">{</span>
@ -229,12 +232,12 @@ using the read-only API key) as an identifier.</p>
<h3>Example Read-Only Response</h3>
<p>When using the read-only API key, the following fields are omitted:
<code>ping_url</code>, <code>update_url</code>, <code>pause_url</code>, <code>channels</code>. An extra <code>unique_key</code> field is
added. This identifier is stable across API calls.</p>
<p>Note: the <code>ping_url</code>, <code>update_url</code> and <code>pause_url</code> fields, although omitted, are not
really secret. The client already knows the check's unique UUID and so can easily
construct these URLs by itself.</p>
<p>When using the read-only API key, SITE_NAME omits the following fields from responses:
<code>ping_url</code>, <code>update_url</code>, <code>pause_url</code>, <code>channels</code>. It adds an extra
<code>unique_key</code> field. This identifier is stable across API calls.</p>
<p>Note: although API omits the <code>ping_url</code>, <code>update_url</code>, and <code>pause_url</code> in read-only
API responses, the client can easily construct these URLs themselves <em>if</em> they know the
check's unique UUID.</p>
<div class="json highlight"><pre><span></span><code><span class="p">{</span>
<span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;Database Backup&quot;</span><span class="p">,</span>
<span class="nt">&quot;tags&quot;</span><span class="p">:</span> <span class="s2">&quot;production db&quot;</span><span class="p">,</span>
@ -257,9 +260,11 @@ construct these URLs by itself.</p>
<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>
<p>With this API call, you can create both Simple and Cron checks:</p>
<ul>
<li>To create a Simple check, specify the <code>timeout</code> parameter.</li>
<li>To create a Cron check, specify the <code>schedule</code> and <code>tz</code> parameters.</li>
</ul>
<h3>Request Parameters</h3>
<dl>
<dt>name</dt>
@ -297,8 +302,9 @@ Example:</p>
<dd>
<p>string, optional, default value: "<em> * </em> * *".</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>If you specify both <code>timeout</code> and <code>schedule</code> parameters,
SITE_NAME will create a Cron check and ignore
the <code>timeout</code> value.</p>
<p>Example for a check running every half-hour:</p>
<p><pre>{"schedule": "0,30 * <em> * </em>"}</pre></p>
</dd>
@ -306,39 +312,40 @@ ignored and "schedule" will be used.</p>
<dd>
<p>string, optional, default value: "UTC".</p>
<p>Server's timezone. This setting only has effect in combination with the
"schedule" parameter.</p>
<code>schedule</code> parameter.</p>
<p>Example:</p>
<p><pre>{"tz": "Europe/Riga"}</pre></p>
</dd>
<dt>manual_resume</dt>
<dd>
<p>boolean, optional, default value: false.</p>
<p>Controls whether a paused ping resumes automatically when pinged (the default),
<p>Controls whether a paused check automatically resumes when pinged (the default)
or not. If set to false, a paused check will leave the paused state when it receives
a ping. If set to true, a paused check will ignore pings and stay paused until it is
either manually resumed from the web dashboard or the <code>manual_resume</code> flag is
changed.</p>
a ping. If set to true, a paused check will ignore pings and stay paused until
you manually resume it from the web dashboard.</p>
</dd>
<dt>channels</dt>
<dd>
<p>string, optional</p>
<p>By default, if a check is created through API, no notification channels
(integrations) are assigned to it. So, when the check goes up or down, no
notifications will get sent.</p>
<p>By default, this API call assigns no integrations to the newly created
check.</p>
<p>Set this field to a special value "*" to automatically assign all existing
integrations.</p>
<p>To assign specific integrations, use a comma-separated list of integration
identifiers. Use the <a href="#list-channels">Get a List of Existing Integrations</a> call to
look up integration identifiers.</p>
identifiers. Use the <a href="#list-channels">Get a List of Existing Integrations</a>
API call to look up the available integration identifiers.</p>
</dd>
<dt>unique</dt>
<dd>
<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>Enables "upsert" functionality. Before creating a check, SITE_NAME looks for
existing checks, filtered by fields listed in <code>unique</code>.</p>
<p>If no matching check is found, SITE_NAME creates a new check and returns it
with the HTTP status code 201.</p>
<p>If a matching check <em>is</em> found, SITE_NAME will update it
and return it with HTTP status code 200.</p>
<p>The accepted values for the <code>unique</code> field are:
<code>name</code>, <code>tags</code>, <code>timeout</code> and <code>grace</code>.</p>
<p>Example:</p>
<p><pre>{"name": "Backups", unique: ["name"]}</pre></p>
<p>In this example, if a check named "Backups" exists, it will be returned.
@ -348,9 +355,9 @@ Otherwise, a new check will be created and returned.</p>
<h3>Response Codes</h3>
<dl>
<dt>201 Created</dt>
<dd>The check was successfully created.</dd>
<dd>A new check was successfully created.</dd>
<dt>200 OK</dt>
<dd>The <code>unique</code> parameter was used and an existing check was matched.</dd>
<dd>An existing check was found and updated.</dd>
<dt>400 Bad Request</dt>
<dd>The request is not well-formed, violates schema, or uses invalid
field values.</dd>


+ 47
- 39
templates/docs/api.md View File

@ -1,7 +1,7 @@
# Management API
SITE_NAME Management API supports listing, creating, updating, pausing and deleting
checks in user's account.
With the Management API, you can programmatically manage checks and integrations
in your account.
## API Endpoints
@ -20,7 +20,7 @@ Endpoint Name | Endpoint Address
## Authentication
Your requests to SITE_NAME Management API must authenticate using an
API key. API keys are project-specific, there are no account-wide API keys.
API key. All API keys are project-specific. There are no account-wide API keys.
By default, a project on SITE_NAME doesn't have an API key. You can create read-write
and read-only API keys in the **Project Settings** page.
@ -38,19 +38,19 @@ read-only key
individual API endpoints for details.
The client can authenticate itself by including an `X-Api-Key: <your-api-key>`
header in a HTTP request. Alternatively, for POST requests with a JSON request body,
the client can include an `api_key` field in the JSON document.
header in an HTTP request. Alternatively, for POST requests with a JSON request body,
the client can put an `api_key` field in the JSON document.
See the [Create a new check](#create-check) section for an example.
## API Requests
For POST requests, the SITE_NAME API expects request body to be
For POST requests, the SITE_NAME API expects the request body to be
a JSON document (*not* a `multipart/form-data` encoded form data).
## API Responses
SITE_NAME uses HTTP status codes wherever possible.
In general, 2xx class indicates success, 4xx indicates an client error,
In general, 2xx class indicates success, 4xx indicates a client error,
and 5xx indicates a server error.
The response may contain a JSON document with additional data.
@ -130,9 +130,13 @@ curl --header "X-Api-Key: your-api-key" SITE_ROOT/api/v1/checks/
}
```
When using the read-only API key, the following fields are omitted:
`ping_url`, `update_url`, `pause_url`, `channels`. An extra `unique_key` field
is added which can be used [to `GET` a check](#get-check) in place of the `UUID`. The `unique_key` identifier is stable across API calls. Example:
When using the read-only API key, SITE_NAME omits the following fields from responses:
`ping_url`, `update_url`, `pause_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.
Example:
```json
{
@ -221,14 +225,13 @@ curl --header "X-Api-Key: your-api-key" SITE_ROOT/api/v1/checks/<uuid>
### Example Read-Only Response
When using the read-only API key, the following fields are omitted:
`ping_url`, `update_url`, `pause_url`, `channels`. An extra `unique_key` field is
added. This identifier is stable across API calls.
When using the read-only API key, SITE_NAME omits the following fields from responses:
`ping_url`, `update_url`, `pause_url`, `channels`. It adds an extra
`unique_key` field. This identifier is stable across API calls.
Note: the `ping_url`, `update_url` and `pause_url` fields, although omitted, are not
really secret. The client already knows the check's unique UUID and so can easily
construct these URLs by itself.
Note: although API omits the `ping_url`, `update_url`, and `pause_url` in read-only
API responses, the client can easily construct these URLs themselves *if* they know the
check's unique UUID.
```json
{
@ -255,9 +258,10 @@ Creates a new check and returns its ping URL.
All request parameters are optional and will use their default
values if omitted.
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.
With this API call, you can 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.
### Request Parameters
@ -302,8 +306,9 @@ schedule
A cron expression defining this check's schedule.
If you specify both "timeout" and "schedule" parameters, "timeout" will be
ignored and "schedule" will be used.
If you specify both `timeout` and `schedule` parameters,
SITE_NAME will create a Cron check and ignore
the `timeout` value.
Example for a check running every half-hour:
@ -313,7 +318,7 @@ tz
: string, optional, default value: "UTC".
Server's timezone. This setting only has effect in combination with the
"schedule" parameter.
`schedule` parameter.
Example:
@ -322,35 +327,38 @@ tz
manual_resume
: boolean, optional, default value: false.
Controls whether a paused ping resumes automatically when pinged (the default),
Controls whether a paused check automatically resumes when pinged (the default)
or not. If set to false, a paused check will leave the paused state when it receives
a ping. If set to true, a paused check will ignore pings and stay paused until it is
either manually resumed from the web dashboard or the `manual_resume` flag is
changed.
a ping. If set to true, a paused check will ignore pings and stay paused until
you manually resume it from the web dashboard.
channels
: string, optional
By default, if a check is created through API, no notification channels
(integrations) are assigned to it. So, when the check goes up or down, no
notifications will get sent.
By default, this API call assigns no integrations to the newly created
check.
Set this field to a special value "*" to automatically assign all existing
integrations.
To assign specific integrations, use a comma-separated list of integration
identifiers. Use the [Get a List of Existing Integrations](#list-channels) call to
look up integration identifiers.
identifiers. Use the [Get a List of Existing Integrations](#list-channels)
API call to look up the available integration identifiers.
unique
: array of string values, optional, default value: [].
Before creating a check, look for existing checks, filtered by fields listed
in `unique`. 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.
Enables "upsert" functionality. Before creating a check, SITE_NAME looks for
existing checks, filtered by fields listed in `unique`.
If no matching check is found, SITE_NAME creates a new check and returns it
with the HTTP status code 201.
If a matching check *is* found, SITE_NAME will update it
and return it with HTTP status code 200.
The accepted values are: `name`, `tags`, `timeout` and `grace`.
The accepted values for the `unique` field are:
`name`, `tags`, `timeout` and `grace`.
Example:
@ -362,10 +370,10 @@ unique
### Response Codes
201 Created
: The check was successfully created.
: A new check was successfully created.
200 OK
: The `unique` parameter was used and an existing check was matched.
: An existing check was found and updated.
400 Bad Request
: The request is not well-formed, violates schema, or uses invalid


+ 8
- 8
templates/docs/http_api.html View File

@ -1,26 +1,26 @@
<h1>Pinging API</h1>
<p>The SITE_NAME pinging API is used for submitting "start", "success" and "fail"
signals ("pings") from the monitored systems.</p>
<p>With the Pinging API, you can signal <strong>success</strong>, <strong>fail</strong>, and <strong>start</strong> events from
your systems.</p>
<h2>General Notes</h2>
<p>All ping endpoints support:</p>
<ul>
<li>HTTP and HTTPS</li>
<li>HTTP 1.0, HTTP 1.1 and HTTP 2</li>
<li>IPv4 and IPv6</li>
<li>HEAD, GET and POST requests methods. The HTTP POST requests
<li>HEAD, GET, and POST requests methods. The HTTP POST requests
can optionally include diagnostic information in the request body.
If the request body looks like a UTF-8 string, SITE_NAME stores the request body
(limited to first 10KB for each received ping).</li>
(limited to the first 10KB for each received ping).</li>
</ul>
<p>Successful responses will have the "200 OK" HTTP response status code and a short
and simple string "OK" in the response body.</p>
"OK" string in the response body.</p>
<h2>Send a "success" Signal</h2>
<div class="text highlight"><pre><span></span><code>HEAD|GET|POST PING_ENDPOINT{uuid}
</code></pre></div>
<p>Signals to SITE_NAME that the job has completed successfully (or, for
continuously running processes, is still running and healthy). The <code>uuid</code> parameter
<p>Signals to SITE_NAME that the job has completed successfully (or,
continuously running processes are still running and healthy). The <code>uuid</code> parameter
is unique for each check.</p>
<p><strong>Example</strong></p>
<div class="http highlight"><pre><span></span><code><span class="nf">GET</span> <span class="nn">/5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278</span> <span class="kr">HTTP</span><span class="o">/</span><span class="m">1.0</span>
@ -45,7 +45,7 @@ OK
</code></pre></div>
<p>Signals to SITE_NAME that the job has failed. Actively signalling a failure
<p>Signals to SITE_NAME that the job has failed. Actively signaling a failure
minimizes the delay from your monitored service failing to you receiving an alert.</p>
<p><strong>Example</strong></p>
<div class="http highlight"><pre><span></span><code><span class="nf">GET</span> <span class="nn">/5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278/fail</span> <span class="kr">HTTP</span><span class="o">/</span><span class="m">1.0</span>


+ 8
- 8
templates/docs/http_api.md View File

@ -1,7 +1,7 @@
# Pinging API
The SITE_NAME pinging API is used for submitting "start", "success" and "fail"
signals ("pings") from the monitored systems.
With the Pinging API, you can signal **success**, **fail**, and **start** events from
your systems.
## General Notes
@ -10,13 +10,13 @@ All ping endpoints support:
* HTTP and HTTPS
* HTTP 1.0, HTTP 1.1 and HTTP 2
* IPv4 and IPv6
* HEAD, GET and POST requests methods. The HTTP POST requests
* HEAD, GET, and POST requests methods. The HTTP POST requests
can optionally include diagnostic information in the request body.
If the request body looks like a UTF-8 string, SITE_NAME stores the request body
(limited to first 10KB for each received ping).
(limited to the first 10KB for each received ping).
Successful responses will have the "200 OK" HTTP response status code and a short
and simple string "OK" in the response body.
"OK" string in the response body.
## Send a "success" Signal
@ -24,8 +24,8 @@ and simple string "OK" in the response body.
HEAD|GET|POST PING_ENDPOINT{uuid}
```
Signals to SITE_NAME that the job has completed successfully (or, for
continuously running processes, is still running and healthy). The `uuid` parameter
Signals to SITE_NAME that the job has completed successfully (or,
continuously running processes are still running and healthy). The `uuid` parameter
is unique for each check.
**Example**
@ -53,7 +53,7 @@ OK
HEAD|GET|POST PING_ENDPOINT{uuid}/fail
```
Signals to SITE_NAME that the job has failed. Actively signalling a failure
Signals to SITE_NAME that the job has failed. Actively signaling a failure
minimizes the delay from your monitored service failing to you receiving an alert.
**Example**


Write Preview
Loading…
Cancel
Save