From c13f65e118afc1ef7f1c8fd82593dc0c3d45eb0c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C4=93teris=20Caune?= Date: Wed, 9 Sep 2020 17:53:24 +0300 Subject: [PATCH] Grammar and style fixes. --- hc/api/tests/test_create_check.py | 10 +++- templates/docs/api.html | 83 +++++++++++++++-------------- templates/docs/api.md | 86 +++++++++++++++++-------------- templates/docs/http_api.html | 16 +++--- templates/docs/http_api.md | 16 +++--- 5 files changed, 116 insertions(+), 95 deletions(-) diff --git a/hc/api/tests/test_create_check.py b/hc/api/tests/test_create_check.py index 90bb01c0..5f836bea 100644 --- a/hc/api/tests/test_create_check.py +++ b/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) diff --git a/templates/docs/api.html b/templates/docs/api.html index 47ee9bd0..4ad10219 100644 --- a/templates/docs/api.html +++ b/templates/docs/api.html @@ -1,6 +1,6 @@

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

@@ -50,7 +50,7 @@ checks in user's account.

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.

@@ -69,15 +69,15 @@ 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 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.

Get a List of Existing Checks

@@ -148,9 +148,12 @@ specified value.

-

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 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 +and Get a list of check's status changes API calls.

+

Example:

{
   "checks": [
     {
@@ -229,12 +232,12 @@ using the read-only API key) as an identifier.

 
 
 
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.

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

+
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: 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.

 
{
   "name": "Database Backup",
   "tags": "production db",
@@ -257,9 +260,11 @@ construct these URLs by itself.

 
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

 

 
name

@@ -297,8 +302,9 @@ Example:

 

 
string, optional, default value: " *  * *".

 
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:

 
{"schedule": "0,30 *  * "}

 

@@ -306,39 +312,40 @@ ignored and "schedule" will be used.

 

 
string, optional, default value: "UTC".

 
Server's timezone. This setting only has effect in combination with the
-"schedule" parameter.

+schedule parameter.

 
Example:

 
{"tz": "Europe/Riga"}

 

 
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 call to
-look up integration identifiers.

+identifiers. Use the Get a List of Existing Integrations
+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.

-
The accepted values are: name, tags, timeout and grace.

+
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 for the unique field are:
+name, tags, timeout and grace.

 
Example:

 
{"name": "Backups", unique: ["name"]}

 
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.

 
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
 field values.

diff --git a/templates/docs/api.md b/templates/docs/api.md
index 316f9a62..a5fd1508 100644
--- a/templates/docs/api.md
+++ b/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: `
-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/
 
 ### 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
diff --git a/templates/docs/http_api.html b/templates/docs/http_api.html
index eae246c9..18c599d6 100644
--- a/templates/docs/http_api.html
+++ b/templates/docs/http_api.html
@@ -1,26 +1,26 @@
 
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

 
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

 
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

 
GET /5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278 HTTP/1.0
@@ -45,7 +45,7 @@ OK
 

 
 
-
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

 
GET /5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278/fail HTTP/1.0
diff --git a/templates/docs/http_api.md b/templates/docs/http_api.md
index 27806e99..66c03d02 100644
--- a/templates/docs/http_api.md
+++ b/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**