With the Pinging API, you can signal success, fail, and start events from +
With the Pinging API, you can signal success, start, and failure events from your systems.
All ping endpoints support:
@@ -14,13 +14,85 @@ If the request body looks like a UTF-8 string, SITE_NAME stores the request bodySuccessful responses will have the "200 OK" HTTP response status code and a short "OK" string in the response body.
-HEAD|GET|POST PING_ENDPOINT{uuid}
+UUIDs and Slugs
+Each Pinging API request needs to uniquely identify a check.
+SITE_NAME supports two ways of identifying a check: by check's UUID,
+or by a combination of project's Ping Key and check's slug.
+Check's UUID is automatically assigned when the check is created. It is
+immutable. You cannot replace the automatically assigned UUID with a manually
+chosen one. When you delete a check, you also lose its UUID and cannot get it back.
+You can look up UUIDs of your checks in web UI or via Management API calls.
+Check's slug is its name with the following transformations applied:
+
+- Convert to ASCII.
+- Convert to lowercase.
+- Remove characters that aren't alphanumerics, underscores, hyphens, or whitespace.
+- Replace any whitespace or repeated dashes with single dashes.
+- Remove leading and trailing whitespace, dashes, and underscores.
+
+For example, if check's name is "Database Backup", its slug is database-backup.
+Check's slug can change. SITE_NAME updates check's slug whenever its name changes.
+Check's slug is not guaranteed to be unique. If multiple checks in the project
+have the same name, they also have the same slug. If you make a Pinging API
+request using a non-unique slug, SITE_NAME will return the "409 Conflict" HTTP status
+code and ignore the request.
+Endpoints
+
+
+
+Endpoint Name
+Endpoint Address
+
+
+
+
+Success (UUID)
+PING_ENDPOINT<uuid>
+
+Start (UUID)
+PING_ENDPOINT<uuid>/start
+
+Failure (UUID)
+PING_ENDPOINT<uuid>/fail
+
+Report script's exit status (UUID)
+PING_ENDPOINT<uuid>/<exitcode>
+
+Success (slug)
+PING_ENDPOINT<ping-key>/<slug>
+
+Start (slug)
+PING_ENDPOINT<ping-key>/<slug>/start
+
+Failure (slug)
+PING_ENDPOINT<ping-key>/<slug>/fail
+
+Report script's exit status (slug)
+PING_ENDPOINT<ping-key>/<slug>/<exitcode>
+
+
+Send a "success" Signal Using UUID
+HEAD|GET|POST PING_ENDPOINT<uuid>
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.
+a continuously running process is still running and healthy).
+SITE_NAME identifies the check by the UUID value included in the URL.
+Response Codes
+
+- 200 OK
+- The request succeeded.
+- 404 Not Found
+- Could not find a check with the specified UUID.
+
Example
GET /5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278 HTTP/1.0
Host: hc-ping.com
@@ -37,12 +109,54 @@ is unique for each check.
OK
-Send a "fail" Signal
-HEAD|GET|POST PING_ENDPOINT{uuid}/fail
+Send a "start" Signal Using UUID
+HEAD|GET|POST PING_ENDPOINT<uuid>/start
+
+
+Sends a "job has started!" message to SITE_NAME. Sending a "start" signal is optional,
+but it enables a few extra features:
+
+- SITE_NAME will measure and display job execution times
+- SITE_NAME will detect if the job runs longer than its configured grace time
+
+SITE_NAME identifies the check by the UUID value included in the URL.
+Response Codes
+
+- 200 OK
+- The request succeeded.
+- 404 Not Found
+- Could not find a check with the specified UUID.
+
+Example
+GET /5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278/start HTTP/1.0
+Host: hc-ping.com
+
+
+HTTP/1.1 200 OK
+Server: nginx
+Date: Wed, 29 Jan 2020 09:58:23 GMT
+Content-Type: text/plain; charset=utf-8
+Content-Length: 2
+Connection: close
+Access-Control-Allow-Origin: *
+
+OK
+
+
+Send a "failure" Signal Using UUID
+HEAD|GET|POST PING_ENDPOINT<uuid>/fail
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.
+SITE_NAME identifies the check by the UUID value included in the URL.
+Response Codes
+
+- 200 OK
+- The request succeeded.
+- 404 Not Found
+- Could not find a check with the specified UUID.
+
Example
GET /5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278/fail HTTP/1.0
Host: hc-ping.com
@@ -59,8 +173,74 @@ minimizes the delay from your monitored service failing to you receiving an aler
OK
-Send a "start" Signal
-HEAD|GET|POST PING_ENDPOINT{uuid}/start
+Report Script's Exit Status (Using UUID)
+HEAD|GET|POST PING_ENDPOINT<uuid>/<exit-status>
+
+
+Sends a success or failure signal depending on the exit status
+included in the URL. The exit status is a 0-255 integer. SITE_NAME
+interprets 0 as success and all other values as failure.
+SITE_NAME identifies the check by the UUID value included in the URL.
+Response Codes
+
+- 200 OK
+- The request succeeded.
+- 400 Bad Request
+- Invalid URL format.
+- 404 Not Found
+- Could not find a check with the specified UUID.
+
+Example
+GET /5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278/1 HTTP/1.0
+Host: hc-ping.com
+
+
+HTTP/1.1 200 OK
+Server: nginx
+Date: Wed, 29 Jan 2020 09:58:23 GMT
+Content-Type: text/plain; charset=utf-8
+Content-Length: 2
+Connection: close
+Access-Control-Allow-Origin: *
+
+OK
+
+
+Send a "success" Signal (Using Slug)
+HEAD|GET|POST PING_ENDPOINT<ping-key>/<slug>
+
+
+Signals to SITE_NAME that the job has completed successfully (or,
+a continuously running process is still running and healthy).
+SITE_NAME identifies the check by project's ping key and check's slug
+included in the URL.
+Response Codes
+
+- 200 OK
+- The request succeeded.
+- 404 Not Found
+- Could not find a check with the specified ping key and slug combination.
+- 409 Conflict
+- Ambiguous, the slug matched multiple checks.
+
+Example
+GET /fqOOd6-F4MMNuCEnzTU01w/database-backup HTTP/1.0
+Host: hc-ping.com
+
+
+HTTP/1.1 200 OK
+Server: nginx
+Date: Wed, 29 Jan 2020 09:58:23 GMT
+Content-Type: text/plain; charset=utf-8
+Content-Length: 2
+Connection: close
+Access-Control-Allow-Origin: *
+
+OK
+
+
+Send a "start" Signal (Using Slug)
+HEAD|GET|POST PING_ENDPOINT<ping-key>/<slug>/start
Sends a "job has started!" message to SITE_NAME. Sending a "start" signal is
@@ -69,8 +249,19 @@ optional, but it enables a few extra features:
SITE_NAME will measure and display job execution times
SITE_NAME will detect if the job runs longer than its configured grace time
+SITE_NAME identifies the check by project's ping key and check's slug
+included in the URL.
+Response Codes
+
+- 200 OK
+- The request succeeded.
+- 404 Not Found
+- Could not find a check with the specified ping key and slug combination.
+- 409 Conflict
+- Ambiguous, the slug matched multiple checks.
+
Example
-GET /5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278/start HTTP/1.0
+GET /fqOOd6-F4MMNuCEnzTU01w/database-backup/start HTTP/1.0
Host: hc-ping.com
@@ -85,15 +276,61 @@ optional, but it enables a few extra features:
OK
-Report Script's Exit Status
-HEAD|GET|POST PING_ENDPOINT{uuid}/{exit-status}
+Send a "failure" Signal (Using slug)
+HEAD|GET|POST PING_ENDPOINT<ping-key/<slug>/fail
+
+
+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.
+SITE_NAME identifies the check by project's ping key and check's slug
+included in the URL.
+Response Codes
+
+- 200 OK
+- The request succeeded.
+- 404 Not Found
+- Could not find a check with the specified ping key and slug combination.
+- 409 Conflict
+- Ambiguous, the slug matched multiple checks.
+
+Example
+GET /fqOOd6-F4MMNuCEnzTU01w/database-backup/fail HTTP/1.0
+Host: hc-ping.com
+
+
+HTTP/1.1 200 OK
+Server: nginx
+Date: Wed, 29 Jan 2020 09:58:23 GMT
+Content-Type: text/plain; charset=utf-8
+Content-Length: 2
+Connection: close
+Access-Control-Allow-Origin: *
+
+OK
+
+
+Report Script's Exit Status (Using Slug)
+HEAD|GET|POST PING_ENDPOINT<ping-key>/<slug>/<exit-status>
Sends a success or failure signal depending on the exit status
included in the URL. The exit status is a 0-255 integer. SITE_NAME
interprets 0 as success and all other values as failure.
+SITE_NAME identifies the check by project's ping key and check's slug
+included in the URL.
+Response Codes
+
+- 200 OK
+- The request succeeded.
+- 400 Bad Request
+- Invalid URL format.
+- 404 Not Found
+- Could not find a check with the specified ping key and slug combination.
+- 409 Conflict
+- Ambiguous, the slug matched multiple checks.
+
Example
-GET /5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278/1 HTTP/1.0
+GET /fqOOd6-F4MMNuCEnzTU01w/database-backup/1 HTTP/1.0
Host: hc-ping.com
diff --git a/templates/docs/http_api.md b/templates/docs/http_api.md
index d2d4cd64..78066ec6 100644
--- a/templates/docs/http_api.md
+++ b/templates/docs/http_api.md
@@ -1,6 +1,6 @@
# Pinging API
-With the Pinging API, you can signal **success**, **fail**, and **start** events from
+With the Pinging API, you can signal **success**, **start**, and **failure** events from
your systems.
## General Notes
@@ -18,15 +18,66 @@ If the request body looks like a UTF-8 string, SITE_NAME stores the request body
Successful responses will have the "200 OK" HTTP response status code and a short
"OK" string in the response body.
-## Send a "success" Signal
+## UUIDs and Slugs
+
+Each Pinging API request needs to uniquely identify a check.
+SITE_NAME supports two ways of identifying a check: by check's UUID,
+or by a combination of project's Ping Key and check's slug.
+
+**Check's UUID** is automatically assigned when the check is created. It is
+immutable. You cannot replace the automatically assigned UUID with a manually
+chosen one. When you delete a check, you also lose its UUID and cannot get it back.
+
+You can look up UUIDs of your checks in web UI or via [Management API](../api/) calls.
+
+**Check's slug** is its name with the following transformations applied:
+
+* Convert to ASCII.
+* Convert to lowercase.
+* Remove characters that aren't alphanumerics, underscores, hyphens, or whitespace.
+* Replace any whitespace or repeated dashes with single dashes.
+* Remove leading and trailing whitespace, dashes, and underscores.
+
+For example, if check's name is "Database Backup", its slug is `database-backup`.
+
+Check's slug **can change**. SITE_NAME updates check's slug whenever its name changes.
+
+Check's slug is **not guaranteed to be unique**. If multiple checks in the project
+have the same name, they also have the same slug. If you make a Pinging API
+request using a non-unique slug, SITE_NAME will return the "409 Conflict" HTTP status
+code and ignore the request.
+
+## Endpoints
+
+Endpoint Name | Endpoint Address
+------------------------------------------------------------|-------
+[Success (UUID)](#success-uuid) | `PING_ENDPOINT`
+[Start (UUID)](#start-uuid) | `PING_ENDPOINT/start`
+[Failure (UUID)](#fail-uuid) | `PING_ENDPOINT/fail`
+[Report script's exit status (UUID)](#exitcode-uuid) | `PING_ENDPOINT/`
+[Success (slug)](#success-slug) | `PING_ENDPOINT/`
+[Start (slug)](#start-slug) | `PING_ENDPOINT//start`
+[Failure (slug)](#fail-slug) | `PING_ENDPOINT//fail`
+[Report script's exit status (slug)](#exitcode-slug) | `PING_ENDPOINT//`
+
+## Send a "success" Signal Using UUID {: #success-uuid .rule }
```text
-HEAD|GET|POST PING_ENDPOINT{uuid}
+HEAD|GET|POST PING_ENDPOINT
```
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.
+a continuously running process is still running and healthy).
+
+SITE_NAME identifies the check by the UUID value included in the URL.
+
+### Response Codes
+
+200 OK
+: The request succeeded.
+
+404 Not Found
+: Could not find a check with the specified UUID.
**Example**
@@ -47,15 +98,66 @@ Access-Control-Allow-Origin: *
OK
```
-## Send a "fail" Signal
+## Send a "start" Signal Using UUID {: #start-uuid .rule }
+
+```text
+HEAD|GET|POST PING_ENDPOINT/start
+```
+
+Sends a "job has started!" message to SITE_NAME. Sending a "start" signal is optional,
+but it enables a few extra features:
+
+* SITE_NAME will measure and display job execution times
+* SITE_NAME will detect if the job runs longer than its configured grace time
+
+SITE_NAME identifies the check by the UUID value included in the URL.
+
+### Response Codes
+
+200 OK
+: The request succeeded.
+
+404 Not Found
+: Could not find a check with the specified UUID.
+
+**Example**
+
+```http
+GET /5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278/start HTTP/1.0
+Host: hc-ping.com
+```
+
+```http
+HTTP/1.1 200 OK
+Server: nginx
+Date: Wed, 29 Jan 2020 09:58:23 GMT
+Content-Type: text/plain; charset=utf-8
+Content-Length: 2
+Connection: close
+Access-Control-Allow-Origin: *
+
+OK
+```
+
+## Send a "failure" Signal Using UUID {: #fail-uuid .rule }
```text
-HEAD|GET|POST PING_ENDPOINT{uuid}/fail
+HEAD|GET|POST PING_ENDPOINT/fail
```
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.
+SITE_NAME identifies the check by the UUID value included in the URL.
+
+### Response Codes
+
+200 OK
+: The request succeeded.
+
+404 Not Found
+: Could not find a check with the specified UUID.
+
**Example**
```http
@@ -75,10 +177,94 @@ Access-Control-Allow-Origin: *
OK
```
-## Send a "start" Signal
+## Report Script's Exit Status (Using UUID) {: #exitcode-uuid .rule }
```text
-HEAD|GET|POST PING_ENDPOINT{uuid}/start
+HEAD|GET|POST PING_ENDPOINT/
+```
+
+Sends a success or failure signal depending on the exit status
+included in the URL. The exit status is a 0-255 integer. SITE_NAME
+interprets 0 as success and all other values as failure.
+
+SITE_NAME identifies the check by the UUID value included in the URL.
+
+### Response Codes
+
+200 OK
+: The request succeeded.
+
+400 Bad Request
+: Invalid URL format.
+
+404 Not Found
+: Could not find a check with the specified UUID.
+
+**Example**
+
+```http
+GET /5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278/1 HTTP/1.0
+Host: hc-ping.com
+```
+
+```http
+HTTP/1.1 200 OK
+Server: nginx
+Date: Wed, 29 Jan 2020 09:58:23 GMT
+Content-Type: text/plain; charset=utf-8
+Content-Length: 2
+Connection: close
+Access-Control-Allow-Origin: *
+
+OK
+```
+
+## Send a "success" Signal (Using Slug) {: #success-slug .rule }
+
+```text
+HEAD|GET|POST PING_ENDPOINT/
+```
+
+Signals to SITE_NAME that the job has completed successfully (or,
+a continuously running process is still running and healthy).
+
+SITE_NAME identifies the check by project's ping key and check's slug
+included in the URL.
+
+### Response Codes
+
+200 OK
+: The request succeeded.
+
+404 Not Found
+: Could not find a check with the specified ping key and slug combination.
+
+409 Conflict
+: Ambiguous, the slug matched multiple checks.
+
+**Example**
+
+```http
+GET /fqOOd6-F4MMNuCEnzTU01w/database-backup HTTP/1.0
+Host: hc-ping.com
+```
+
+```http
+HTTP/1.1 200 OK
+Server: nginx
+Date: Wed, 29 Jan 2020 09:58:23 GMT
+Content-Type: text/plain; charset=utf-8
+Content-Length: 2
+Connection: close
+Access-Control-Allow-Origin: *
+
+OK
+```
+
+## Send a "start" Signal (Using Slug) {: #start-slug .rule }
+
+```text
+HEAD|GET|POST PING_ENDPOINT//start
```
Sends a "job has started!" message to SITE_NAME. Sending a "start" signal is
@@ -87,10 +273,24 @@ optional, but it enables a few extra features:
* SITE_NAME will measure and display job execution times
* SITE_NAME will detect if the job runs longer than its configured grace time
+SITE_NAME identifies the check by project's ping key and check's slug
+included in the URL.
+
+### Response Codes
+
+200 OK
+: The request succeeded.
+
+404 Not Found
+: Could not find a check with the specified ping key and slug combination.
+
+409 Conflict
+: Ambiguous, the slug matched multiple checks.
+
**Example**
```http
-GET /5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278/start HTTP/1.0
+GET /fqOOd6-F4MMNuCEnzTU01w/database-backup/start HTTP/1.0
Host: hc-ping.com
```
@@ -106,20 +306,79 @@ Access-Control-Allow-Origin: *
OK
```
-## Report Script's Exit Status
+## Send a "failure" Signal (Using slug) {: #fail-slug .rule }
```text
-HEAD|GET|POST PING_ENDPOINT{uuid}/{exit-status}
+HEAD|GET|POST PING_ENDPOINT/fail
+```
+
+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.
+
+SITE_NAME identifies the check by project's ping key and check's slug
+included in the URL.
+
+### Response Codes
+
+200 OK
+: The request succeeded.
+
+404 Not Found
+: Could not find a check with the specified ping key and slug combination.
+
+409 Conflict
+: Ambiguous, the slug matched multiple checks.
+
+**Example**
+
+```http
+GET /fqOOd6-F4MMNuCEnzTU01w/database-backup/fail HTTP/1.0
+Host: hc-ping.com
+```
+
+```http
+HTTP/1.1 200 OK
+Server: nginx
+Date: Wed, 29 Jan 2020 09:58:23 GMT
+Content-Type: text/plain; charset=utf-8
+Content-Length: 2
+Connection: close
+Access-Control-Allow-Origin: *
+
+OK
+```
+
+## Report Script's Exit Status (Using Slug) {: #exitcode-slug .rule }
+
+```text
+HEAD|GET|POST PING_ENDPOINT//
```
Sends a success or failure signal depending on the exit status
included in the URL. The exit status is a 0-255 integer. SITE_NAME
interprets 0 as success and all other values as failure.
+SITE_NAME identifies the check by project's ping key and check's slug
+included in the URL.
+
+### Response Codes
+
+200 OK
+: The request succeeded.
+
+400 Bad Request
+: Invalid URL format.
+
+404 Not Found
+: Could not find a check with the specified ping key and slug combination.
+
+409 Conflict
+: Ambiguous, the slug matched multiple checks.
+
**Example**
```http
-GET /5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278/1 HTTP/1.0
+GET /fqOOd6-F4MMNuCEnzTU01w/database-backup/1 HTTP/1.0
Host: hc-ping.com
```
@@ -134,3 +393,4 @@ Access-Control-Allow-Origin: *
OK
```
+