From c3d8ee096526106073eb8289ea1f5938b2603203 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C4=93teris=20Caune?= Date: Mon, 15 Jun 2020 13:25:55 +0300 Subject: [PATCH] Update API docs. --- templates/docs/api.html | 67 +++++++++++++++++++++++++++++++++++++++++ templates/docs/api.md | 67 ++++++++++++++++++++--------------------- 2 files changed, 100 insertions(+), 34 deletions(-) diff --git a/templates/docs/api.html b/templates/docs/api.html index 202bcf14..3c3d2554 100644 --- a/templates/docs/api.html +++ b/templates/docs/api.html @@ -43,6 +43,10 @@ checks in user's account.

GET SITE_ROOT/api/v1/checks/<uuid>/pings/ +Get a list of check's status changes +GET SITE_ROOT/api/v1/checks/<uuid>/flips/ + + Get a list of existing integrations GET SITE_ROOT/api/v1/channels/ @@ -679,6 +683,69 @@ number of returned pings depends on account's billing plan: 100 for free account +

Get a list of check's status changes

+

GET SITE_ROOT/api/v1/checks/<uuid>/flips/
+GET SITE_ROOT/api/v1/checks/<unique_key>/flips/

+

Returns a list of "flips" this check has experienced. A flip is a change of status +(from "down" to "up", or from "up" to "down").

+

Query String Parameters

+
+
seconds=<value>
+
+

Returns the flips from the last value seconds

+

Example:

+

SITE_ROOT/api/v1/checks/<uuid|unique_key>/flips/?seconds=3600

+
+
start=<value>
+
+

Returns flips that are newer than the specified UNIX timestamp.

+

Example:

+

SITE_ROOT/api/v1/checks/<uuid|unique_key>/flips/?start=1592214380

+
+
end=<value>
+
+

Returns flips that are older than the specified UNIX timestamp.

+

Example:

+

SITE_ROOT/api/v1/checks/<uuid|unique_key>/flips/?end=1592217980

+
+
+

Response Codes

+
+
200 OK
+
The request succeeded.
+
400 Bad Request
+
Invalid query parameters.
+
401 Unauthorized
+
The API key is either missing or invalid.
+
403 Forbidden
+
Access denied, wrong API key.
+
404 Not Found
+
The specified check does not exist.
+
+

Example Request

+
curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/flips/ \
+    --header "X-Api-Key: your-api-key"
+
+ + +

Example Response

+
[
+    {
+      "timestamp": "2020-03-23T10:18:23+00:00",
+      "up": 1
+    },
+    {
+      "timestamp": "2020-03-23T10:17:15+00:00",
+      "up": 0
+    },
+    {
+      "timestamp": "2020-03-23T10:16:18+00:00",
+      "up": 1
+    }
+]
+
+ +

Get a List of Existing Integrations

GET SITE_ROOT/api/v1/channels/

Returns a list of integrations belonging to the project.

diff --git a/templates/docs/api.md b/templates/docs/api.md index 8b2ab1e4..631c8bec 100644 --- a/templates/docs/api.md +++ b/templates/docs/api.md @@ -14,7 +14,8 @@ Endpoint Name | Endpoint Address [Update an existing check](#update-check) | `POST SITE_ROOT/api/v1/checks/` [Pause monitoring of a check](#pause-check) | `POST SITE_ROOT/api/v1/checks//pause` [Delete check](#delete-check) | `DELETE SITE_ROOT/api/v1/checks/` -[Get a list of check's logged pings](#list-pings) | `GET SITE_ROOT/api/v1/checks//pings/` +[Get a list of check's logged pings](#list-pings) | `GET SITE_ROOT/api/v1/checks//pings/` +[Get a list of check's status changes](#list-flips) | `GET SITE_ROOT/api/v1/checks//flips/` [Get a list of existing integrations](#list-channels) | `GET SITE_ROOT/api/v1/channels/` ## Authentication @@ -746,33 +747,36 @@ curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pings/ \ ``` -## Get a list of check's flips {: #list-flips .rule } +## Get a list of check's status changes {: #list-flips .rule } -`GET SITE_ROOT/api/v1/checks//flips/` or `GET SITE_ROOT/api/v1/checks//flips/` +`GET SITE_ROOT/api/v1/checks//flips/`
+`GET SITE_ROOT/api/v1/checks//flips/` -Returns a list of flips this check has experienced. A flip is a change of status (up, or down). - -This endpoint returns the status of a check for the period of time passed according to the below parameters. If no parameters are passed, the default is to return flips occuring in the previous 3600 seconds (`/?seconds=3600`), which is the last hour. +Returns a list of "flips" this check has experienced. A flip is a change of status +(from "down" to "up", or from "up" to "down"). ### Query String Parameters -Either the seconds or the start (and end) parameters can be passed. Passing both the seconds parameter and the start/end parameters will return a 400 error (see below). - seconds=<value> -: Filters the checks, and returns the flip history in the last `n` seconds +: Returns the flips from the last `value` seconds Example: `SITE_ROOT/api/v1/checks//flips/?seconds=3600` -start=<value>&end=<value> -: Filters the checks, and returns the flip history between the start and end timestamps. - - If provided, both values must be unix timestamps. The `end` parameter is optional and defaults to the timestamp of the current date and time. +start=<value> +: Returns flips that are newer than the specified UNIX timestamp. Example: - `SITE_ROOT/api/v1/checks//flips/?seconds=3600` + `SITE_ROOT/api/v1/checks//flips/?start=1592214380` + +end=<value> +: Returns flips that are older than the specified UNIX timestamp. + + Example: + + `SITE_ROOT/api/v1/checks//flips/?end=1592217980` ### Response Codes @@ -781,7 +785,7 @@ start=<value>&end=<value> : The request succeeded. 400 Bad Request -: Both a seconds and a start or end query string parameter has been passed, which is unsupported. +: Invalid query parameters. 401 Unauthorized : The API key is either missing or invalid. @@ -802,25 +806,20 @@ curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/flips/ \ ### Example Response ```json -{ - "name": "My First Check", - "tags": "", - "desc": "", - "grace": 3600, - "n_pings": 2, - "status": "up", - "last_ping": "2020-06-12T02:18:46+00:00", - "next_ping": "2020-06-13T02:18:46+00:00", - "manual_resume": false, - "history": [ - { - "timestamp": "2020-03-23T23:30:18.767Z", - "up": 1 - } - ], - "unique_key": "e855898bebff1756cde7c571319d877d07a38dab", - "timeout": 86400 -} +[ + { + "timestamp": "2020-03-23T10:18:23+00:00", + "up": 1 + }, + { + "timestamp": "2020-03-23T10:17:15+00:00", + "up": 0 + }, + { + "timestamp": "2020-03-23T10:16:18+00:00", + "up": 1 + } +] ``` ## Get a List of Existing Integrations {: #list-channels .rule }