Grammar and style fixes.

hc/api/tests/test_create_check.py

@@ -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)

templates/docs/api.html

@@ -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>

templates/docs/api.md

@@ -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

templates/docs/http_api.html

@@ -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>

templates/docs/http_api.md

@@ -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**