From be66ec73e5f099b8546296ad6d4be8c35030ab14 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C4=93teris=20Caune?= Date: Wed, 15 Sep 2021 11:39:05 +0300 Subject: [PATCH] Add the slug-based endpoints in Ping API docs --- static/css/docs.css | 9 +- templates/docs/http_api.html | 263 ++++++++++++++++++++++++++++++-- templates/docs/http_api.md | 286 +++++++++++++++++++++++++++++++++-- 3 files changed, 529 insertions(+), 29 deletions(-) diff --git a/static/css/docs.css b/static/css/docs.css index 90950734..552a3a97 100644 --- a/static/css/docs.css +++ b/static/css/docs.css @@ -81,16 +81,19 @@ h2.rule { } } -.docs-api table { +.docs-api table, +.docs-http_api table { width: 100%; margin: 8px 0; } -.docs-api th { +.docs-api th, +.docs-http_api th { display: none; } -.docs-api td { +.docs-api td, +.docs-http_api td { padding: 8px; border: 1px solid var(--border-color); } diff --git a/templates/docs/http_api.html b/templates/docs/http_api.html index 68bb5e4c..0a11fe4e 100644 --- a/templates/docs/http_api.html +++ b/templates/docs/http_api.html @@ -1,5 +1,5 @@

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

All ping endpoints support:

@@ -14,13 +14,85 @@ 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

-
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 NameEndpoint 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
 ```
+