From dab0c4200e349cfb0d62c9e5d3038063adb47c93 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C4=93teris=20Caune?= Date: Mon, 2 Mar 2020 13:37:29 +0200 Subject: [PATCH] API reference in Markdown --- CHANGELOG.md | 1 + hc/front/management/commands/pygmentize.py | 15 - hc/front/management/commands/render_docs.py | 2 +- hc/front/urls.py | 1 - hc/front/views.py | 14 +- static/css/docs.css | 76 +-- templates/docs/api.html | 487 ++++++++++++++++ templates/docs/api.md | 533 ++++++++++++++++++ templates/front/base_docs.html | 4 +- templates/front/docs_api.html | 500 ---------------- templates/front/docs_single.html | 2 +- .../snippets/create_check_request_a.html | 4 - .../front/snippets/create_check_request_a.txt | 3 - .../snippets/create_check_request_b.html | 3 - .../front/snippets/create_check_request_b.txt | 2 - .../front/snippets/create_check_response.html | 16 - .../front/snippets/create_check_response.txt | 15 - .../front/snippets/delete_check_request.html | 3 - .../front/snippets/delete_check_request.txt | 2 - .../front/snippets/list_channels_request.html | 2 - .../front/snippets/list_channels_request.txt | 1 - .../snippets/list_channels_response.html | 15 - .../front/snippets/list_channels_response.txt | 14 - .../front/snippets/list_checks_request.html | 2 - .../front/snippets/list_checks_request.txt | 1 - .../front/snippets/list_checks_response.html | 36 -- .../front/snippets/list_checks_response.txt | 35 -- .../list_checks_response_readonly.html | 29 - .../list_checks_response_readonly.txt | 28 - .../front/snippets/pause_check_request.html | 3 - .../front/snippets/pause_check_request.txt | 2 - .../front/snippets/pause_check_response.html | 16 - .../front/snippets/pause_check_response.txt | 15 - .../front/snippets/python_requests_fail.html | 4 +- .../front/snippets/python_requests_start.html | 2 +- .../snippets/update_check_request_a.html | 4 - .../front/snippets/update_check_request_a.txt | 3 - .../snippets/update_check_request_b.html | 3 - .../front/snippets/update_check_request_b.txt | 2 - 39 files changed, 1070 insertions(+), 830 deletions(-) create mode 100644 templates/docs/api.html create mode 100644 templates/docs/api.md delete mode 100644 templates/front/docs_api.html delete mode 100644 templates/front/snippets/create_check_request_a.html delete mode 100644 templates/front/snippets/create_check_request_a.txt delete mode 100644 templates/front/snippets/create_check_request_b.html delete mode 100644 templates/front/snippets/create_check_request_b.txt delete mode 100644 templates/front/snippets/create_check_response.html delete mode 100644 templates/front/snippets/create_check_response.txt delete mode 100644 templates/front/snippets/delete_check_request.html delete mode 100644 templates/front/snippets/delete_check_request.txt delete mode 100644 templates/front/snippets/list_channels_request.html delete mode 100644 templates/front/snippets/list_channels_request.txt delete mode 100644 templates/front/snippets/list_channels_response.html delete mode 100644 templates/front/snippets/list_channels_response.txt delete mode 100644 templates/front/snippets/list_checks_request.html delete mode 100644 templates/front/snippets/list_checks_request.txt delete mode 100644 templates/front/snippets/list_checks_response.html delete mode 100644 templates/front/snippets/list_checks_response.txt delete mode 100644 templates/front/snippets/list_checks_response_readonly.html delete mode 100644 templates/front/snippets/list_checks_response_readonly.txt delete mode 100644 templates/front/snippets/pause_check_request.html delete mode 100644 templates/front/snippets/pause_check_request.txt delete mode 100644 templates/front/snippets/pause_check_response.html delete mode 100644 templates/front/snippets/pause_check_response.txt delete mode 100644 templates/front/snippets/update_check_request_a.html delete mode 100644 templates/front/snippets/update_check_request_a.txt delete mode 100644 templates/front/snippets/update_check_request_b.html delete mode 100644 templates/front/snippets/update_check_request_b.txt diff --git a/CHANGELOG.md b/CHANGELOG.md index c2c67538..7c68be38 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,7 @@ All notable changes to this project will be documented in this file. - Improved UI to invite users from account's other projects (#258) - Experimental Prometheus metrics endpoint (#300) - Don't store user's current project in DB, put it explicitly in page URLs (#336) +- API reference in Markdown ### Bug Fixes - The "render_docs" command checks if markdown and pygments is installed (#329) diff --git a/hc/front/management/commands/pygmentize.py b/hc/front/management/commands/pygmentize.py index 3d32a217..73c25083 100644 --- a/hc/front/management/commands/pygmentize.py +++ b/hc/front/management/commands/pygmentize.py @@ -44,18 +44,3 @@ class Command(BaseCommand): _process("powershell", lexers.shell.PowerShellLexer()) _process("powershell_inline", lexers.shell.BashLexer()) _process("ruby", lexers.RubyLexer()) - - # API examples - _process("list_checks_request", lexers.BashLexer()) - _process("list_checks_response", lexers.JsonLexer()) - _process("list_checks_response_readonly", lexers.JsonLexer()) - _process("list_channels_request", lexers.BashLexer()) - _process("list_channels_response", lexers.JsonLexer()) - _process("create_check_request_a", lexers.BashLexer()) - _process("create_check_request_b", lexers.BashLexer()) - _process("update_check_request_a", lexers.BashLexer()) - _process("update_check_request_b", lexers.BashLexer()) - _process("create_check_response", lexers.JsonLexer()) - _process("pause_check_request", lexers.BashLexer()) - _process("pause_check_response", lexers.JsonLexer()) - _process("delete_check_request", lexers.BashLexer()) diff --git a/hc/front/management/commands/render_docs.py b/hc/front/management/commands/render_docs.py index fe65de49..c50a5f81 100644 --- a/hc/front/management/commands/render_docs.py +++ b/hc/front/management/commands/render_docs.py @@ -19,7 +19,7 @@ class Command(BaseCommand): self.stdout.write(f" pip install {e.name}\n\n") return - extensions = ["fenced_code", "codehilite", "tables"] + extensions = ["fenced_code", "codehilite", "tables", "def_list", "attr_list"] ec = {"codehilite": {"css_class": "highlight"}} docs_path = os.path.join(settings.BASE_DIR, "templates/docs") diff --git a/hc/front/urls.py b/hc/front/urls.py index 43d45056..5fdff5d1 100644 --- a/hc/front/urls.py +++ b/hc/front/urls.py @@ -91,7 +91,6 @@ urlpatterns = [ path("integrations/", include(channel_urls)), path("projects//", include(project_urls)), path("docs/", views.serve_doc, name="hc-docs"), - path("docs/api/", views.docs_api, name="hc-docs-api"), path("docs/cron/", views.docs_cron, name="hc-docs-cron"), path("docs//", views.serve_doc, name="hc-serve-doc"), ] diff --git a/hc/front/views.py b/hc/front/views.py index 675aebdd..ba9cf6e0 100644 --- a/hc/front/views.py +++ b/hc/front/views.py @@ -278,6 +278,7 @@ def serve_doc(request, doc="introduction"): content = open(path, "r", encoding="utf-8").read() content = content.replace("SITE_NAME", settings.SITE_NAME) + content = content.replace("SITE_ROOT", settings.SITE_ROOT) content = content.replace("PING_URL", settings.PING_ENDPOINT + "your-uuid-here") content = content.replace("PING_ENDPOINT", settings.PING_ENDPOINT) content = content.replace("IMG_URL", os.path.join(settings.STATIC_URL, "img/docs")) @@ -296,19 +297,6 @@ def serve_doc(request, doc="introduction"): return render(request, "front/docs_single.html", ctx) -def docs_api(request): - ctx = { - "page": "docs", - "section": "api", - "SITE_ROOT": settings.SITE_ROOT, - "PING_ENDPOINT": settings.PING_ENDPOINT, - "default_timeout": int(DEFAULT_TIMEOUT.total_seconds()), - "default_grace": int(DEFAULT_GRACE.total_seconds()), - } - - return render(request, "front/docs_api.html", ctx) - - def docs_cron(request): return render(request, "front/docs_cron.html", {}) diff --git a/static/css/docs.css b/static/css/docs.css index db1709dd..dbc6a1f4 100644 --- a/static/css/docs.css +++ b/static/css/docs.css @@ -35,46 +35,12 @@ li + li.nav-header { font-family: monospace; } -.docs-heading { - margin-top: 40px; -} - h2.rule { border-top: 3px solid #eee; margin-top: 30px; padding-top: 30px; } -h3.api-section { - font-size: 14px; - font-weight: bold; - margin: 20px 0; -} - -h3.docs-example { - margin-top: 40px; -} - -.api-path { - font-family: monospace; - font-weight: bold; - margin-bottom: 1em; - background: #f5f5f5; - color: #333; - display: inline-block; - padding: 2px 4px; - border-radius: 2px; -} - -a.section { - color: #000; - text-decoration: none; -} - -a.section:hover { - text-decoration: none; -} - .page-docs code { padding: 2px 4px; font-size: 90%; @@ -105,6 +71,12 @@ a.section:hover { font-weight: bold; } +.docs-content h3 { + font-size: 14px; + font-weight: bold; + margin: 20px 0; +} + .docs-content ul { padding-left: 15px; } @@ -124,3 +96,39 @@ a.section:hover { max-width: 100%; } } + +.docs-api table { + width: 100%; + margin: 8px 0; +} + +.docs-api th { + display: none; +} + +.docs-api td { + padding: 8px; + border: 1px solid #ddd; +} + + +.docs-api dl { + display: grid; + grid-template-columns: 120px auto; +} + +.docs-api dt { + font-weight: normal; + font-family: "Lucida Console", Monaco, monospace; +} + +.docs-api dt, .docs-api dd { + border-top: 1px solid #DDD; + padding: 8px 0; +} + +.rule + p code { + font-size: 14px; + font-weight: bold; + padding: 2px 4px; +} diff --git a/templates/docs/api.html b/templates/docs/api.html new file mode 100644 index 00000000..f86b80be --- /dev/null +++ b/templates/docs/api.html @@ -0,0 +1,487 @@ +

API Reference

+

SITE_NAME REST API supports listing, creating, updating, pausing and deleting +checks in user's account.

+

API Endpoints

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Endpoint NameEndpoint Address
Get a list of existing checksGET SITE_ROOT/api/v1/checks/
Create a new checkPOST SITE_ROOT/api/v1/checks/
Update an existing checkPOST SITE_ROOT/api/v1/checks/<uuid>
Pause monitoring of a checkPOST SITE_ROOT/api/v1/checks/<uuid>/pause
Delete checkDELETE SITE_ROOT/api/v1/checks/<uuid>
Get a list of existing integrationsGET SITE_ROOT/api/v1/channels/
+

Authentication

+

Your requests to SITE_NAME REST API must authenticate using an +API key. Each project in your SITE_NAME account has separate API keys. +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.

+ + + + + + + + + + + + + + + + + +
Key TypeDescription
Regular API keyHave full access to all documented API endpoints.
Read-only API keyOnly work with the Get a list of existing checks endpoint. Some fields are omitted from the API responses.
+

The client can authenticate itself by sending an appropriate HTTP +request header. The header's name should be X-Api-Key and +its value should be your API key.

+

Alternatively, for POST requests with a JSON request body, +the client can include an api_key field in the JSON document. +See below the "Create a check" section for an example.

+

API Requests

+

For POST requests, the SITE_NAME API expects 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, +and 5xx indicates a server error.

+

The response may contain a JSON document with additional data.

+

Get a List of Existing Checks

+

GET SITE_ROOT/api/v1/checks/

+

Returns a list of checks belonging to the user, optionally filtered by +one or more tags.

+

Query String Parameters

+
+
tag=<value>
+
+

Filters the checks, and returns only the checks that are tagged with the +specified value.

+

This parameter can be repeated multiple times.

+

Example:

+

SITE_ROOT/api/v1/checks/?tag=foo&amp;tag=bar

+
+
+

Example Request

+
curl --header "X-Api-Key: your-api-key" SITE_ROOT/api/v1/checks/
+
+ + +

Example Response

+
{
+  "checks": [
+    {
+      "channels": "4ec5a071-2d08-4baa-898a-eb4eb3cd6941,746a083e-f542-4554-be1a-707ce16d3acc",
+      "desc": "Longer free-form description goes here",
+      "grace": 900,
+      "last_ping": "2017-01-04T13:24:39.903464+00:00",
+      "n_pings": 1,
+      "name": "Api test 1",
+      "next_ping": "2017-01-04T14:24:39.903464+00:00",
+      "pause_url": "SITE_ROOT/api/v1/checks/662ebe36-ecab-48db-afe3-e20029cb71e6/pause",
+      "ping_url": "PING_ENDPOINT662ebe36-ecab-48db-afe3-e20029cb71e6",
+      "status": "up",
+      "tags": "foo",
+      "timeout": 3600,
+      "update_url": "SITE_ROOT/api/v1/checks/662ebe36-ecab-48db-afe3-e20029cb71e6"
+    },
+    {
+      "channels": "",
+      "desc": "",
+      "grace": 3600,
+      "last_ping": null,
+      "n_pings": 0,
+      "name": "Api test 2",
+      "next_ping": null,
+      "pause_url": "SITE_ROOT/api/v1/checks/9d17c61f-5c4f-4cab-b517-11e6b2679ced/pause",
+      "ping_url": "PING_ENDPOINT9d17c61f-5c4f-4cab-b517-11e6b2679ced",
+      "schedule": "0/10 * * * *",
+      "status": "new",
+      "tags": "bar baz",
+      "tz": "UTC",
+      "update_url": "SITE_ROOT/api/v1/checks/9d17c61f-5c4f-4cab-b517-11e6b2679ced"
+    }
+  ]
+}
+
+ + +

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

+
{
+  "checks": [
+    {
+      "desc": "Longer free-form description goes here",
+      "grace": 900,
+      "last_ping": "2017-01-04T13:24:39.903464+00:00",
+      "n_pings": 1,
+      "name": "Api test 1",
+      "status": "up",
+      "tags": "foo",
+      "timeout": 3600,
+      "unique_key": "2872190d95224bad120f41d3c06aab94b8175bb6"
+    },
+    {
+      "desc": "",
+      "grace": 3600,
+      "last_ping": null,
+      "n_pings": 0,
+      "name": "Api test 2",
+      "next_ping": null,
+      "schedule": "0/10 * * * *",
+      "status": "new",
+      "tags": "bar baz",
+      "tz": "UTC",
+      "unique_key": "9b5fc29129560ff2c5c1803803a7415e4f80cf7e"
+    }
+  ]
+}
+
+ + +

Create a Check

+

POST SITE_ROOT/api/v1/checks/

+

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.

+

Request Parameters

+
+
name
+
+

string, optional, default value: ""

+

Name for the new check.

+
+
tags
+
+

string, optional, default value: ""

+

A space-delimited list of tags for the new check. +Example:

+

{"tags": "reports staging"}

+
+
desc
+
+

string, optional.

+

Description for the check.

+
+
timeout
+
+

number, optional, default value: {{ default_timeout }}.

+

A number of seconds, the expected period of this check.

+

Minimum: 60 (one minute), maximum: 2592000 (30 days).

+

Example for 5 minute timeout:

+

{"kind": "simple", "timeout": 300}

+
+
grace
+
+

number, optional, default value: {{ default_grace }}.

+

A number of seconds, the grace period for this check.

+

Minimum: 60 (one minute), maximum: 2592000 (30 days).

+
+
schedule
+
+

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.

+

Example for a check running every half-hour:

+

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

+
+
tz
+
+

string, optional, default value: "UTC".

+

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

+

Example:

+

{"tz": "Europe/Riga"}

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

+

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.

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

+

Example:

+

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

+

In this example, if a check named "Backups" exists, it will be returned. +Otherwise, a new check will be created and returned.

+
+
+

Response Codes

+
+
201 Created
+
Returned if the check was successfully created.
+
200 OK
+
Returned if the unique parameter was used and an existing check was matched.
+
403 Forbidden
+
Returned if the account's check limit has been reached. For free accounts, +the limit is 20 checks per account.
+
+

Example Request

+
curl SITE_ROOT/api/v1/checks/ \
+    --header "X-Api-Key: your-api-key" \
+    --data '{"name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}'
+
+ + +

Or, alternatively:

+
curl SITE_ROOT/api/v1/checks/ \
+    --data '{"api_key": "your-api-key", "name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}'
+
+ + +

Example Response

+
{
+  "channels": "",
+  "desc": "",
+  "grace": 60,
+  "last_ping": null,
+  "n_pings": 0,
+  "name": "Backups",
+  "next_ping": null,
+  "pause_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause",
+  "ping_url": "PING_ENDPOINTf618072a-7bde-4eee-af63-71a77c5723bc",
+  "status": "new",
+  "tags": "prod www",
+  "timeout": 3600,
+  "update_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc",
+}
+
+ + +

Update an Existing Check

+

POST SITE_ROOT/api/v1/checks/<uuid>

+

Updates an existing check. All request parameters are optional. The check is +updated only with the supplied request parameters. If any parameter is omitted, +its value is left unchanged.

+

Request Parameters

+
+
name
+
+

string, optional.

+

Name for the check.

+
+
tags
+
+

string, optional.

+

A space-delimited list of tags for the check.

+

Example:

+

{"tags": "reports staging"}

+
+
desc
+
+

string, optional.

+

Description for the check.

+
+
timeout
+
+

number, optional.

+

A number of seconds, the expected period of this check.

+

Minimum: 60 (one minute), maximum: 2592000 (30 days).

+

Example for 5 minute timeout:

+

{"kind": "simple", "timeout": 300}

+
+
grace
+
+

number, optional.

+

A number of seconds, the grace period for this check.

+

Minimum: 60 (one minute), maximum: 2592000 (30 days).

+
+
schedule
+
+

string, optional.

+

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.

+

Example for a check running every half-hour:

+

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

+
+
tz
+
+

string, optional.

+

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

+

Example:

+

{"tz": "Europe/Riga"}

+
+
channels
+
+

string, optional.

+

Set this field to a special value "*" to automatically assign all existing +notification channels.

+

Set this field to a special value "" (empty string) to automatically unassign +all notification channels.

+

Set this field to a comma-separated list of channel identifiers to assign +specific notification channels.

+

Example:

+

{"channels": "4ec5a071-2d08-4baa-898a-eb4eb3cd6941,746a083e-f542-4554-be1a-707ce16d3acc"}

+
+
+

Response Codes

+
+
200 OK
+
Returned if the check was successfully updated.
+
+

Example Request

+
curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc \
+    --header "X-Api-Key: your-api-key" \
+    --data '{"name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}'
+
+ + +

Or, alternatively:

+
curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc \
+    --data '{"api_key": "your-api-key", "name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}'
+
+ + +

Example Response

+
{
+  "channels": "",
+  "desc": "",
+  "grace": 60,
+  "last_ping": null,
+  "n_pings": 0,
+  "name": "Backups",
+  "next_ping": null,
+  "pause_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause",
+  "ping_url": "PING_ENDPOINTf618072a-7bde-4eee-af63-71a77c5723bc",
+  "status": "new",
+  "tags": "prod www",
+  "timeout": 3600,
+  "update_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc",
+}
+
+ + +

Pause Monitoring of a Check

+

POST SITE_ROOT/api/v1/checks/<uuid>/pause

+

Disables monitoring for a check, without removing it. The check goes into a "paused" +state. You can resume monitoring of the check by pinging it.

+

This API call has no request parameters.

+

Example Request

+
curl SITE_ROOT/api/v1/checks/0c8983c9-9d73-446f-adb5-0641fdacc9d4/pause \
+    --request POST --header "X-Api-Key: your-api-key" --data ""
+
+ + +

Note: the --data "" argument forces curl to send a Content-Length request header +even though the request body is empty. For HTTP POST requests, the Content-Length +header is sometimes required by some network proxies and web servers.

+

Example Response

+
{
+  "channels": "",
+  "desc": "",
+  "grace": 60,
+  "last_ping": null,
+  "n_pings": 0,
+  "name": "Backups",
+  "next_ping": null,
+  "pause_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause",
+  "ping_url": "PING_ENDPOINTf618072a-7bde-4eee-af63-71a77c5723bc",
+  "status": "paused",
+  "tags": "prod www",
+  "timeout": 3600,
+  "update_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc"
+}
+
+ + +

Delete Check

+

DELETE SITE_ROOT/api/v1/checks/<uuid>

+

Permanently deletes the check from user's account. Returns JSON representation of the +check that was just deleted.

+

This API call has no request parameters.

+

Example Request

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

Example Response

+
{
+  "channels": "",
+  "desc": "",
+  "grace": 60,
+  "last_ping": null,
+  "n_pings": 0,
+  "name": "Backups",
+  "next_ping": null,
+  "pause_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause",
+  "ping_url": "PING_ENDPOINTf618072a-7bde-4eee-af63-71a77c5723bc",
+  "status": "new",
+  "tags": "prod www",
+  "timeout": 3600,
+  "update_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc",
+}
+
+ + +

Get a List of Existing Integrations

+

GET SITE_ROOT/api/v1/channels/

+

Returns a list of integrations belonging to the user.

+

Example Request

+
curl --header "X-Api-Key: your-api-key" SITE_ROOT/api/v1/channels/
+
+ + +

Example Response

+
{
+  "channels": [
+    {
+      "id": "4ec5a071-2d08-4baa-898a-eb4eb3cd6941",
+      "name": "My Work Email",
+      "kind": "email"
+    },
+    {
+      "id": "746a083e-f542-4554-be1a-707ce16d3acc",
+      "name": "My Phone",
+      "kind": "sms"
+    }
+  ]
+}
+
\ No newline at end of file diff --git a/templates/docs/api.md b/templates/docs/api.md new file mode 100644 index 00000000..f0b78d7c --- /dev/null +++ b/templates/docs/api.md @@ -0,0 +1,533 @@ +# API Reference + +SITE_NAME REST API supports listing, creating, updating, pausing and deleting +checks in user's account. + +## API Endpoints + +Endpoint Name | Endpoint Address +------------------------------------------------------|------- +[Get a list of existing checks](#list-checks) | `GET SITE_ROOT/api/v1/checks/` +[Create a new check](#create-check) | `POST SITE_ROOT/api/v1/checks/` +[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 existing integrations](#list-channels) | `GET SITE_ROOT/api/v1/channels/` + +## Authentication + +Your requests to SITE_NAME REST API must authenticate using an +API key. Each project in your SITE_NAME account has separate API keys. +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. + +Key Type | Description +-------------------|------------ +Regular API key | Have full access to all documented API endpoints. +Read-only API key | Only work with the [Get a list of existing checks](#list-checks) endpoint. Some fields are omitted from the API responses. + +The client can authenticate itself by sending an appropriate HTTP +request header. The header's name should be `X-Api-Key` and +its value should be your API key. + + +Alternatively, for POST requests with a JSON request body, +the client can include an `api_key` field in the JSON document. +See below the "Create a check" section for an example. + +## API Requests + +For POST requests, the SITE_NAME API expects 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, +and 5xx indicates a server error. + +The response may contain a JSON document with additional data. + +## Get a List of Existing Checks {: #list-checks .rule } + +`GET SITE_ROOT/api/v1/checks/` + +Returns a list of checks belonging to the user, optionally filtered by +one or more tags. + +### Query String Parameters + +tag=<value> +: Filters the checks, and returns only the checks that are tagged with the + specified value. + + This parameter can be repeated multiple times. + + Example: + + `SITE_ROOT/api/v1/checks/?tag=foo&tag=bar` + +### Example Request + +```bash +curl --header "X-Api-Key: your-api-key" SITE_ROOT/api/v1/checks/ +``` + +### Example Response + +```json +{ + "checks": [ + { + "channels": "4ec5a071-2d08-4baa-898a-eb4eb3cd6941,746a083e-f542-4554-be1a-707ce16d3acc", + "desc": "Longer free-form description goes here", + "grace": 900, + "last_ping": "2017-01-04T13:24:39.903464+00:00", + "n_pings": 1, + "name": "Api test 1", + "next_ping": "2017-01-04T14:24:39.903464+00:00", + "pause_url": "SITE_ROOT/api/v1/checks/662ebe36-ecab-48db-afe3-e20029cb71e6/pause", + "ping_url": "PING_ENDPOINT662ebe36-ecab-48db-afe3-e20029cb71e6", + "status": "up", + "tags": "foo", + "timeout": 3600, + "update_url": "SITE_ROOT/api/v1/checks/662ebe36-ecab-48db-afe3-e20029cb71e6" + }, + { + "channels": "", + "desc": "", + "grace": 3600, + "last_ping": null, + "n_pings": 0, + "name": "Api test 2", + "next_ping": null, + "pause_url": "SITE_ROOT/api/v1/checks/9d17c61f-5c4f-4cab-b517-11e6b2679ced/pause", + "ping_url": "PING_ENDPOINT9d17c61f-5c4f-4cab-b517-11e6b2679ced", + "schedule": "0/10 * * * *", + "status": "new", + "tags": "bar baz", + "tz": "UTC", + "update_url": "SITE_ROOT/api/v1/checks/9d17c61f-5c4f-4cab-b517-11e6b2679ced" + } + ] +} +``` + +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. Example: + +```json +{ + "checks": [ + { + "desc": "Longer free-form description goes here", + "grace": 900, + "last_ping": "2017-01-04T13:24:39.903464+00:00", + "n_pings": 1, + "name": "Api test 1", + "status": "up", + "tags": "foo", + "timeout": 3600, + "unique_key": "2872190d95224bad120f41d3c06aab94b8175bb6" + }, + { + "desc": "", + "grace": 3600, + "last_ping": null, + "n_pings": 0, + "name": "Api test 2", + "next_ping": null, + "schedule": "0/10 * * * *", + "status": "new", + "tags": "bar baz", + "tz": "UTC", + "unique_key": "9b5fc29129560ff2c5c1803803a7415e4f80cf7e" + } + ] +} +``` + + +## Create a Check {: #create-check .rule } +`POST SITE_ROOT/api/v1/checks/` + +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. + +### Request Parameters + +name +: string, optional, default value: "" + + Name for the new check. + +tags +: string, optional, default value: "" + + A space-delimited list of tags for the new check. + Example: + + 
{"tags": "reports staging"}
+ +desc +: string, optional. + + Description for the check. + +timeout +: number, optional, default value: {{ default_timeout }}. + + A number of seconds, the expected period of this check. + + Minimum: 60 (one minute), maximum: 2592000 (30 days). + + Example for 5 minute timeout: + + 
{"kind": "simple", "timeout": 300}
+ +grace +: number, optional, default value: {{ default_grace }}. + + A number of seconds, the grace period for this check. + + Minimum: 60 (one minute), maximum: 2592000 (30 days). + +schedule +: 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. + + Example for a check running every half-hour: + + 
{"schedule": "0,30 * * * *"}
+ +tz +: string, optional, default value: "UTC". + + Server's timezone. This setting only has effect in combination with the + "schedule" paremeter. + + Example: + + 
{"tz": "Europe/Riga"}
+ +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. + + 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. + +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`. + + Example: + + 
{"name": "Backups", unique: ["name"]}
+ + In this example, if a check named "Backups" exists, it will be returned. + Otherwise, a new check will be created and returned. + +### Response Codes + +201 Created +: Returned if the check was successfully created. + +200 OK +: Returned if the `unique` parameter was used and an existing check was matched. + +403 Forbidden +: Returned if the account's check limit has been reached. For free accounts, + the limit is 20 checks per account. + +### Example Request + +```bash +curl SITE_ROOT/api/v1/checks/ \ + --header "X-Api-Key: your-api-key" \ + --data '{"name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}' +``` + +Or, alternatively: + +```bash +curl SITE_ROOT/api/v1/checks/ \ + --data '{"api_key": "your-api-key", "name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}' +``` + +### Example Response + +```json +{ + "channels": "", + "desc": "", + "grace": 60, + "last_ping": null, + "n_pings": 0, + "name": "Backups", + "next_ping": null, + "pause_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause", + "ping_url": "PING_ENDPOINTf618072a-7bde-4eee-af63-71a77c5723bc", + "status": "new", + "tags": "prod www", + "timeout": 3600, + "update_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc", +} +``` + +## Update an Existing Check {: #update-check .rule } + +`POST SITE_ROOT/api/v1/checks/` + +Updates an existing check. All request parameters are optional. The check is +updated only with the supplied request parameters. If any parameter is omitted, +its value is left unchanged. + +### Request Parameters + +name +: string, optional. + + Name for the check. + +tags +: string, optional. + + A space-delimited list of tags for the check. + + Example: + + 
{"tags": "reports staging"}
+ +desc +: string, optional. + + Description for the check. + +timeout +: number, optional. + + A number of seconds, the expected period of this check. + + Minimum: 60 (one minute), maximum: 2592000 (30 days). + + Example for 5 minute timeout: + + 
{"kind": "simple", "timeout": 300}
+ +grace +: number, optional. + + A number of seconds, the grace period for this check. + + Minimum: 60 (one minute), maximum: 2592000 (30 days). + +schedule +: string, optional. + + 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. + + Example for a check running every half-hour: + + 
{"schedule": "0,30 * * * *"}
+ +tz +: string, optional. + + Server's timezone. This setting only has effect in combination with the + "schedule" paremeter. + + Example: + + 
{"tz": "Europe/Riga"}
+ +channels +: string, optional. + + Set this field to a special value "*" to automatically assign all existing + notification channels. + + Set this field to a special value "" (empty string) to automatically *unassign* + all notification channels. + + Set this field to a comma-separated list of channel identifiers to assign + specific notification channels. + + Example: + + 
{"channels": "4ec5a071-2d08-4baa-898a-eb4eb3cd6941,746a083e-f542-4554-be1a-707ce16d3acc"}
+ + +### Response Codes + +200 OK +: Returned if the check was successfully updated. + +### Example Request + +```bash +curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc \ + --header "X-Api-Key: your-api-key" \ + --data '{"name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}' +``` + +Or, alternatively: + +```bash +curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc \ + --data '{"api_key": "your-api-key", "name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}' +``` + +### Example Response + +```json +{ + "channels": "", + "desc": "", + "grace": 60, + "last_ping": null, + "n_pings": 0, + "name": "Backups", + "next_ping": null, + "pause_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause", + "ping_url": "PING_ENDPOINTf618072a-7bde-4eee-af63-71a77c5723bc", + "status": "new", + "tags": "prod www", + "timeout": 3600, + "update_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc", +} +``` + +## Pause Monitoring of a Check {: #pause-check .rule } + +`POST SITE_ROOT/api/v1/checks//pause` + +Disables monitoring for a check, without removing it. The check goes into a "paused" +state. You can resume monitoring of the check by pinging it. + +This API call has no request parameters. + +### Example Request + +```bash +curl SITE_ROOT/api/v1/checks/0c8983c9-9d73-446f-adb5-0641fdacc9d4/pause \ + --request POST --header "X-Api-Key: your-api-key" --data "" +``` + +Note: the `--data ""` argument forces curl to send a `Content-Length` request header +even though the request body is empty. For HTTP POST requests, the `Content-Length` +header is sometimes required by some network proxies and web servers. + +### Example Response + +```json +{ + "channels": "", + "desc": "", + "grace": 60, + "last_ping": null, + "n_pings": 0, + "name": "Backups", + "next_ping": null, + "pause_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause", + "ping_url": "PING_ENDPOINTf618072a-7bde-4eee-af63-71a77c5723bc", + "status": "paused", + "tags": "prod www", + "timeout": 3600, + "update_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc" +} +``` + +## Delete Check {: #delete-check .rule } + +`DELETE SITE_ROOT/api/v1/checks/` + +Permanently deletes the check from user's account. Returns JSON representation of the +check that was just deleted. + +This API call has no request parameters. + +### Example Request + +```bash +curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc \ + --request DELETE --header "X-Api-Key: your-api-key" +``` + +### Example Response + +```json +{ + "channels": "", + "desc": "", + "grace": 60, + "last_ping": null, + "n_pings": 0, + "name": "Backups", + "next_ping": null, + "pause_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause", + "ping_url": "PING_ENDPOINTf618072a-7bde-4eee-af63-71a77c5723bc", + "status": "new", + "tags": "prod www", + "timeout": 3600, + "update_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc", +} +``` + +## Get a List of Existing Integrations {: #list-channels .rule } + +`GET SITE_ROOT/api/v1/channels/` + +Returns a list of integrations belonging to the user. + +### Example Request + +```bash +curl --header "X-Api-Key: your-api-key" SITE_ROOT/api/v1/channels/ +``` + +### Example Response + +```json +{ + "channels": [ + { + "id": "4ec5a071-2d08-4baa-898a-eb4eb3cd6941", + "name": "My Work Email", + "kind": "email" + }, + { + "id": "746a083e-f542-4554-be1a-707ce16d3acc", + "name": "My Phone", + "kind": "sms" + } + ] +} +``` diff --git a/templates/front/base_docs.html b/templates/front/base_docs.html index 8b3004b6..277ad4ca 100644 --- a/templates/front/base_docs.html +++ b/templates/front/base_docs.html @@ -33,9 +33,7 @@ {% include "front/docs_nav_item.html" with slug="attaching_logs" title="Attaching logs" %}
  • Developer Tools
    • - - Management API - + {% include "front/docs_nav_item.html" with slug="api" title="Management API" %} {% include "front/docs_nav_item.html" with slug="resources" title="Third-party resources" %}
  • Cron
    • diff --git a/templates/front/docs_api.html b/templates/front/docs_api.html deleted file mode 100644 index bb147283..00000000 --- a/templates/front/docs_api.html +++ /dev/null @@ -1,500 +0,0 @@ -{% extends "front/base_docs.html" %} -{% load compress static hc_extras %} - -{% block title %}API Reference - {% site_name %}{% endblock %} - -{% block description %} - -{% endblock %} - -{% block docs_content %} - -

    API Reference

    -

    {% site_name %} REST API supports listing, creating, - updating, pausing and deleting checks in user's account. -

    - -

    API Endpoints

    - - - - - - - - - - - - - - - - - - - - - - - - - -
    Get a list of existing checks - GET {{ SITE_ROOT }}/api/v1/checks/ -
    Create a new check - POST {{ SITE_ROOT }}/api/v1/checks/ -
    Update an existing check - POST {{ SITE_ROOT }}/api/v1/checks/<code> -
    Pause monitoring of a check - POST {{ SITE_ROOT }}/api/v1/checks/<code>/pause -
    Delete check - DELETE {{ SITE_ROOT }}/api/v1/checks/<code> -
    Get a list of existing integrations - GET {{ SITE_ROOT }}/api/v1/channels/ -
    - -

    Authentication

    -

    Your requests to {% site_name %} REST API must authenticate using an -API key. Each project in your {% site_name %} account has separate API keys. -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. -

    - - - - - - - - - - -
    Regular API keysHave full access to all documented API endpoints.
    Read-only API keysOnly work with the - Get a list of existing checks - endpoint. Some fields are omitted from the API responses.
    - -

    The client can authenticate itself by sending an appropriate HTTP -request header. The header's name should be X-Api-Key and -its value should be your API key. -

    - -

    Alternatively, for POST requests with a JSON request body, - the client can include an api_key field in the JSON document. - See below the "Create a check" section for an example. -

    - -

    API Requests

    - -

    -For POST requests, the {% site_name %} API expects 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, -and 5xx indicates a server error. -

    - -

    -The response may contain a JSON document with additional data. -

    - - - - -

    Get a List of Existing Checks

    -     - -
    GET {{ SITE_ROOT }}/api/v1/checks/
    - -

    Returns a list of checks belonging to the user, optionally filtered by -one or more tags.

    - -

    Query String Parameters

    - - - - - -
    tag=<value> -

    - Filters the checks, and returns only the checks that - are tagged with the specified value. -

    -

    - This parameter can be repeated multiple times. -

    -

    Example:

    - 
    {{ SITE_ROOT }}/api/v1/checks/?tag=foo&tag=bar
    -
    - -

    Example Request

    -{% include "front/snippets/list_checks_request.html" %} - -

    Example Response

    -{% include "front/snippets/list_checks_response.html" %} - -

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

    -{% include "front/snippets/list_checks_response_readonly.html" %} - - - - -

    Create a Check

    -     - -
    POST {{ SITE_ROOT }}/api/v1/checks/
    - - - -

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

    - -

    Request Parameters

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    name -

    string, optional, default value: ""

    -

    Name for the new check.

    -
    tags -

    string, optional, default value: ""

    -

    A space-delimited list of tags for the new check.

    -

    Example:

    - 
    {"tags": "reports staging"}
    -
    desc -

    string, optional.

    -

    Description for the check.

    -
    timeout -

    number, optional, default value: {{ default_timeout }}.

    -

    A number of seconds, the expected period of this check.

    -

    Minimum: 60 (one minute), maximum: 2592000 (30 days).

    -

    Example for 5 minute timeout:

    - 
    {"kind": "simple", "timeout": 300}
    -
    grace -

    number, optional, default value: {{ default_grace }}.

    -

    A number of seconds, the grace period for this check.

    -

    Minimum: 60 (one minute), maximum: 2592000 (30 days).

    -
    schedule -

    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.

    -

    Example for a check running every half-hour:

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

    string, optional, default value: "UTC".

    -

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

    -

    Example:

    - 
    {"tz": "Europe/Riga"}
    -
    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.

    - -

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

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

    - -

    Example:

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

    In this example, if a check named "Backups" exists, it will - be returned. Otherwise, a new check will be created and - returned.

    -
    - -

    Response Codes

    - - - - - - - - - - - - - -
    201 CreatedReturned if the check was successfully created.
    200 OKReturned if the unique parameter was used and an - existing check was matched.
    403 ForbiddenReturned if the account's check limit has been reached. - For free accounts, the limit is 20 checks per account.
    - -

    Example Request

    -{% include "front/snippets/create_check_request_a.html" %} -
    -

    Or, alternatively:

    -{% include "front/snippets/create_check_request_b.html" %} - - -

    Example Response

    -{% include "front/snippets/create_check_response.html" %} - - - - -

    Update an Existing Check

    -     - -
    POST {{ SITE_ROOT }}/api/v1/checks/<code>
    - - - -

    - Updates an existing check. All request parameters are optional. The - check is updated only with the supplied request parameters. - If any parameter is omitted, its value is left unchanged. -

    - -

    Request Parameters

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    name -

    string, optional.

    -

    Name for the check.

    -
    tags -

    string, optional.

    -

    A space-delimited list of tags for the check.

    -

    Example:

    - 
    {"tags": "reports staging"}
    -
    desc -

    string, optional.

    -

    Description for the check.

    -
    timeout -

    number, optional.

    -

    A number of seconds, the expected period of this check.

    -

    Minimum: 60 (one minute), maximum: 2592000 (30 days).

    -

    Example for 5 minute timeout:

    - 
    {"kind": "simple", "timeout": 300}
    -
    grace -

    number, optional.

    -

    A number of seconds, the grace period for this check.

    -

    Minimum: 60 (one minute), maximum: 2592000 (30 days).

    -
    schedule -

    string, optional.

    -

    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.

    -

    Example for a check running every half-hour:

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

    string, optional.

    -

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

    -

    Example:

    - 
    {"tz": "Europe/Riga"}
    -
    channels -

    string, optional.

    -

    Set this field to a special value "*" - to automatically assign all existing notification channels. -

    -

    Set this field to a special value "" (empty string) - to automatically unassign all notification channels. -

    -

    Set this field to a comma-separated list of channel identifiers - to assign specific notification channels. -

    -

    Example:

    - 
    {"channels": "4ec5a071-2d08-4baa-898a-eb4eb3cd6941,746a083e-f542-4554-be1a-707ce16d3acc"}
    -
    - -

    Response Codes

    - - - - - -
    200 OKReturned if the check was successfully updated.
    - -

    Example Request

    -{% include "front/snippets/update_check_request_a.html" %} -
    -

    Or, alternatively:

    -{% include "front/snippets/update_check_request_b.html" %} - - -

    Example Response

    -{% include "front/snippets/create_check_response.html" %} - - - - -

    Pause Monitoring of a Check

    -     - -
    POST {{ SITE_ROOT }}/api/v1/checks/<uuid>/pause
    - -

    - Disables monitoring for a check, without removing it. The check goes - into a "paused" state. You can resume monitoring of the check by pinging - it. -

    -

    - This API call has no request parameters. -

    - -

    Example Request

    - -{% include "front/snippets/pause_check_request.html" %} - -

    Note: the --data "" argument forces curl to send a -Content-Length request header even though the request body -is empty. For HTTP POST requests, the Content-Length header -is sometimes required by some network proxies and web servers. -

    - -

    Example Response

    -{% include "front/snippets/pause_check_response.html" %} - - - - -

    Delete Check

    -     - -
    DELETE {{ SITE_ROOT }}/api/v1/checks/<uuid>
    - -

    - Permanently deletes the check from user's account. Returns JSON - representation of the check that was just deleted. -

    -

    - This API call has no request parameters. -

    - -

    Example Request

    - -{% include "front/snippets/delete_check_request.html" %} - -

    Example Response

    -{% include "front/snippets/create_check_response.html" %} - - - - -

    Get a List of Existing Integrations

    -     - -
    GET {{ SITE_ROOT }}/api/v1/channels/
    - -

    Returns a list of integrations belonging to the user.

    - -

    Example Request

    -{% include "front/snippets/list_channels_request.html" %} - -

    Example Response

    -{% include "front/snippets/list_channels_response.html" %} - - -{% endblock %} - -{% block scripts %} -{% compress js %} - - - - -{% endcompress %} -{% endblock %} diff --git a/templates/front/docs_single.html b/templates/front/docs_single.html index e484b4d1..2bd71ca5 100644 --- a/templates/front/docs_single.html +++ b/templates/front/docs_single.html @@ -6,7 +6,7 @@ {% block keywords %}{% endblock %} {% block docs_content %} -
    {{ content|safe }}
    +
    {{ content|safe }}
    {% endblock %} {% block scripts %} diff --git a/templates/front/snippets/create_check_request_a.html b/templates/front/snippets/create_check_request_a.html deleted file mode 100644 index e6cc06ff..00000000 --- a/templates/front/snippets/create_check_request_a.html +++ /dev/null @@ -1,4 +0,0 @@ -
    curl {{ SITE_ROOT }}/api/v1/checks/ \
-    --header "X-Api-Key: your-api-key" \
-    --data '{"name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}'
-
    diff --git a/templates/front/snippets/create_check_request_a.txt b/templates/front/snippets/create_check_request_a.txt deleted file mode 100644 index e7e4d5db..00000000 --- a/templates/front/snippets/create_check_request_a.txt +++ /dev/null @@ -1,3 +0,0 @@ -curl SITE_ROOT/api/v1/checks/ \ - --header "X-Api-Key: your-api-key" \ - --data '{"name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}' diff --git a/templates/front/snippets/create_check_request_b.html b/templates/front/snippets/create_check_request_b.html deleted file mode 100644 index a824f47f..00000000 --- a/templates/front/snippets/create_check_request_b.html +++ /dev/null @@ -1,3 +0,0 @@ -
    curl {{ SITE_ROOT }}/api/v1/checks/ \
-    --data '{"api_key": "your-api-key", "name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}'
-
    diff --git a/templates/front/snippets/create_check_request_b.txt b/templates/front/snippets/create_check_request_b.txt deleted file mode 100644 index 40838f18..00000000 --- a/templates/front/snippets/create_check_request_b.txt +++ /dev/null @@ -1,2 +0,0 @@ -curl SITE_ROOT/api/v1/checks/ \ - --data '{"api_key": "your-api-key", "name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}' diff --git a/templates/front/snippets/create_check_response.html b/templates/front/snippets/create_check_response.html deleted file mode 100644 index 56da02f6..00000000 --- a/templates/front/snippets/create_check_response.html +++ /dev/null @@ -1,16 +0,0 @@ -
    {
-  "channels": "",
-  "desc": "",
-  "grace": 60,
-  "last_ping": null,
-  "n_pings": 0,
-  "name": "Backups",
-  "next_ping": null,
-  "pause_url": "{{ SITE_ROOT }}/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause",
-  "ping_url": "{{ PING_ENDPOINT }}f618072a-7bde-4eee-af63-71a77c5723bc",
-  "status": "new",
-  "tags": "prod www",
-  "timeout": 3600,
-  "update_url": "{{ SITE_ROOT }}/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc",
-}
-
    diff --git a/templates/front/snippets/create_check_response.txt b/templates/front/snippets/create_check_response.txt deleted file mode 100644 index 3465b42b..00000000 --- a/templates/front/snippets/create_check_response.txt +++ /dev/null @@ -1,15 +0,0 @@ -{ - "channels": "", - "desc": "", - "grace": 60, - "last_ping": null, - "n_pings": 0, - "name": "Backups", - "next_ping": null, - "pause_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause", - "ping_url": "PING_ENDPOINTf618072a-7bde-4eee-af63-71a77c5723bc", - "status": "new", - "tags": "prod www", - "timeout": 3600, - "update_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc", -} \ No newline at end of file diff --git a/templates/front/snippets/delete_check_request.html b/templates/front/snippets/delete_check_request.html deleted file mode 100644 index d8c91835..00000000 --- a/templates/front/snippets/delete_check_request.html +++ /dev/null @@ -1,3 +0,0 @@ -
    curl {{ SITE_ROOT }}/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc \
-    --request DELETE --header "X-Api-Key: your-api-key"
-
    diff --git a/templates/front/snippets/delete_check_request.txt b/templates/front/snippets/delete_check_request.txt deleted file mode 100644 index bb873346..00000000 --- a/templates/front/snippets/delete_check_request.txt +++ /dev/null @@ -1,2 +0,0 @@ -curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc \ - --request DELETE --header "X-Api-Key: your-api-key" diff --git a/templates/front/snippets/list_channels_request.html b/templates/front/snippets/list_channels_request.html deleted file mode 100644 index bdb42f64..00000000 --- a/templates/front/snippets/list_channels_request.html +++ /dev/null @@ -1,2 +0,0 @@ -
    curl --header "X-Api-Key: your-api-key" {{ SITE_ROOT }}/api/v1/channels/
-
    diff --git a/templates/front/snippets/list_channels_request.txt b/templates/front/snippets/list_channels_request.txt deleted file mode 100644 index abefe167..00000000 --- a/templates/front/snippets/list_channels_request.txt +++ /dev/null @@ -1 +0,0 @@ -curl --header "X-Api-Key: your-api-key" SITE_ROOT/api/v1/channels/ \ No newline at end of file diff --git a/templates/front/snippets/list_channels_response.html b/templates/front/snippets/list_channels_response.html deleted file mode 100644 index de1d81a0..00000000 --- a/templates/front/snippets/list_channels_response.html +++ /dev/null @@ -1,15 +0,0 @@ -
    {
-  "channels": [
-    {
-      "id": "4ec5a071-2d08-4baa-898a-eb4eb3cd6941",
-      "name": "My Work Email",
-      "kind": "email"
-    },
-    {
-      "id": "746a083e-f542-4554-be1a-707ce16d3acc",
-      "name": "My Phone",
-      "kind": "sms"
-    }
-  ]
-}
-
    diff --git a/templates/front/snippets/list_channels_response.txt b/templates/front/snippets/list_channels_response.txt deleted file mode 100644 index ded65355..00000000 --- a/templates/front/snippets/list_channels_response.txt +++ /dev/null @@ -1,14 +0,0 @@ -{ - "channels": [ - { - "id": "4ec5a071-2d08-4baa-898a-eb4eb3cd6941", - "name": "My Work Email", - "kind": "email" - }, - { - "id": "746a083e-f542-4554-be1a-707ce16d3acc", - "name": "My Phone", - "kind": "sms" - } - ] -} \ No newline at end of file diff --git a/templates/front/snippets/list_checks_request.html b/templates/front/snippets/list_checks_request.html deleted file mode 100644 index c0a277a6..00000000 --- a/templates/front/snippets/list_checks_request.html +++ /dev/null @@ -1,2 +0,0 @@ -
    curl --header "X-Api-Key: your-api-key" {{ SITE_ROOT }}/api/v1/checks/
-
    diff --git a/templates/front/snippets/list_checks_request.txt b/templates/front/snippets/list_checks_request.txt deleted file mode 100644 index 079a6ba2..00000000 --- a/templates/front/snippets/list_checks_request.txt +++ /dev/null @@ -1 +0,0 @@ -curl --header "X-Api-Key: your-api-key" SITE_ROOT/api/v1/checks/ \ No newline at end of file diff --git a/templates/front/snippets/list_checks_response.html b/templates/front/snippets/list_checks_response.html deleted file mode 100644 index a13b6556..00000000 --- a/templates/front/snippets/list_checks_response.html +++ /dev/null @@ -1,36 +0,0 @@ -
    {
-  "checks": [
-    {
-      "channels": "4ec5a071-2d08-4baa-898a-eb4eb3cd6941,746a083e-f542-4554-be1a-707ce16d3acc",
-      "desc": "Longer free-form description goes here",
-      "grace": 900,
-      "last_ping": "2017-01-04T13:24:39.903464+00:00",
-      "n_pings": 1,
-      "name": "Api test 1",
-      "next_ping": "2017-01-04T14:24:39.903464+00:00",
-      "pause_url": "{{ SITE_ROOT }}/api/v1/checks/662ebe36-ecab-48db-afe3-e20029cb71e6/pause",
-      "ping_url": "{{ PING_ENDPOINT }}662ebe36-ecab-48db-afe3-e20029cb71e6",
-      "status": "up",
-      "tags": "foo",
-      "timeout": 3600,
-      "update_url": "{{ SITE_ROOT }}/api/v1/checks/662ebe36-ecab-48db-afe3-e20029cb71e6"
-    },
-    {
-      "channels": "",
-      "desc": "",
-      "grace": 3600,
-      "last_ping": null,
-      "n_pings": 0,
-      "name": "Api test 2",
-      "next_ping": null,
-      "pause_url": "{{ SITE_ROOT }}/api/v1/checks/9d17c61f-5c4f-4cab-b517-11e6b2679ced/pause",
-      "ping_url": "{{ PING_ENDPOINT }}9d17c61f-5c4f-4cab-b517-11e6b2679ced",
-      "schedule": "0/10 * * * *",
-      "status": "new",
-      "tags": "bar baz",
-      "tz": "UTC",
-      "update_url": "{{ SITE_ROOT }}/api/v1/checks/9d17c61f-5c4f-4cab-b517-11e6b2679ced"
-    }
-  ]
-}
-
    diff --git a/templates/front/snippets/list_checks_response.txt b/templates/front/snippets/list_checks_response.txt deleted file mode 100644 index 425412e1..00000000 --- a/templates/front/snippets/list_checks_response.txt +++ /dev/null @@ -1,35 +0,0 @@ -{ - "checks": [ - { - "channels": "4ec5a071-2d08-4baa-898a-eb4eb3cd6941,746a083e-f542-4554-be1a-707ce16d3acc", - "desc": "Longer free-form description goes here", - "grace": 900, - "last_ping": "2017-01-04T13:24:39.903464+00:00", - "n_pings": 1, - "name": "Api test 1", - "next_ping": "2017-01-04T14:24:39.903464+00:00", - "pause_url": "SITE_ROOT/api/v1/checks/662ebe36-ecab-48db-afe3-e20029cb71e6/pause", - "ping_url": "PING_ENDPOINT662ebe36-ecab-48db-afe3-e20029cb71e6", - "status": "up", - "tags": "foo", - "timeout": 3600, - "update_url": "SITE_ROOT/api/v1/checks/662ebe36-ecab-48db-afe3-e20029cb71e6" - }, - { - "channels": "", - "desc": "", - "grace": 3600, - "last_ping": null, - "n_pings": 0, - "name": "Api test 2", - "next_ping": null, - "pause_url": "SITE_ROOT/api/v1/checks/9d17c61f-5c4f-4cab-b517-11e6b2679ced/pause", - "ping_url": "PING_ENDPOINT9d17c61f-5c4f-4cab-b517-11e6b2679ced", - "schedule": "0/10 * * * *", - "status": "new", - "tags": "bar baz", - "tz": "UTC", - "update_url": "SITE_ROOT/api/v1/checks/9d17c61f-5c4f-4cab-b517-11e6b2679ced" - } - ] -} \ No newline at end of file diff --git a/templates/front/snippets/list_checks_response_readonly.html b/templates/front/snippets/list_checks_response_readonly.html deleted file mode 100644 index d123702e..00000000 --- a/templates/front/snippets/list_checks_response_readonly.html +++ /dev/null @@ -1,29 +0,0 @@ -
    {
-  "checks": [
-    {
-      "desc": "Longer free-form description goes here",
-      "grace": 900,
-      "last_ping": "2017-01-04T13:24:39.903464+00:00",
-      "n_pings": 1,
-      "name": "Api test 1",
-      "status": "up",
-      "tags": "foo",
-      "timeout": 3600,
-      "unique_key": "2872190d95224bad120f41d3c06aab94b8175bb6"
-    },
-    {
-      "desc": "",
-      "grace": 3600,
-      "last_ping": null,
-      "n_pings": 0,
-      "name": "Api test 2",
-      "next_ping": null,
-      "schedule": "0/10 * * * *",
-      "status": "new",
-      "tags": "bar baz",
-      "tz": "UTC",
-      "unique_key": "9b5fc29129560ff2c5c1803803a7415e4f80cf7e"
-    }
-  ]
-}
-
    diff --git a/templates/front/snippets/list_checks_response_readonly.txt b/templates/front/snippets/list_checks_response_readonly.txt deleted file mode 100644 index a6e43685..00000000 --- a/templates/front/snippets/list_checks_response_readonly.txt +++ /dev/null @@ -1,28 +0,0 @@ -{ - "checks": [ - { - "desc": "Longer free-form description goes here", - "grace": 900, - "last_ping": "2017-01-04T13:24:39.903464+00:00", - "n_pings": 1, - "name": "Api test 1", - "status": "up", - "tags": "foo", - "timeout": 3600, - "unique_key": "2872190d95224bad120f41d3c06aab94b8175bb6" - }, - { - "desc": "", - "grace": 3600, - "last_ping": null, - "n_pings": 0, - "name": "Api test 2", - "next_ping": null, - "schedule": "0/10 * * * *", - "status": "new", - "tags": "bar baz", - "tz": "UTC", - "unique_key": "9b5fc29129560ff2c5c1803803a7415e4f80cf7e" - } - ] -} \ No newline at end of file diff --git a/templates/front/snippets/pause_check_request.html b/templates/front/snippets/pause_check_request.html deleted file mode 100644 index 2b47ea13..00000000 --- a/templates/front/snippets/pause_check_request.html +++ /dev/null @@ -1,3 +0,0 @@ -
    curl {{ SITE_ROOT }}/api/v1/checks/0c8983c9-9d73-446f-adb5-0641fdacc9d4/pause \
-    --request POST --header "X-Api-Key: your-api-key" --data ""
-
    diff --git a/templates/front/snippets/pause_check_request.txt b/templates/front/snippets/pause_check_request.txt deleted file mode 100644 index c01eaff3..00000000 --- a/templates/front/snippets/pause_check_request.txt +++ /dev/null @@ -1,2 +0,0 @@ -curl SITE_ROOT/api/v1/checks/0c8983c9-9d73-446f-adb5-0641fdacc9d4/pause \ - --request POST --header "X-Api-Key: your-api-key" --data "" diff --git a/templates/front/snippets/pause_check_response.html b/templates/front/snippets/pause_check_response.html deleted file mode 100644 index 8300d7f9..00000000 --- a/templates/front/snippets/pause_check_response.html +++ /dev/null @@ -1,16 +0,0 @@ -
    {
-  "channels": "",
-  "desc": "",
-  "grace": 60,
-  "last_ping": null,
-  "n_pings": 0,
-  "name": "Backups",
-  "next_ping": null,
-  "pause_url": "{{ SITE_ROOT }}/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause",
-  "ping_url": "{{ PING_ENDPOINT }}f618072a-7bde-4eee-af63-71a77c5723bc",
-  "status": "paused",
-  "tags": "prod www",
-  "timeout": 3600,
-  "update_url": "{{ SITE_ROOT }}/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc"
-}
-
    diff --git a/templates/front/snippets/pause_check_response.txt b/templates/front/snippets/pause_check_response.txt deleted file mode 100644 index d06b5654..00000000 --- a/templates/front/snippets/pause_check_response.txt +++ /dev/null @@ -1,15 +0,0 @@ -{ - "channels": "", - "desc": "", - "grace": 60, - "last_ping": null, - "n_pings": 0, - "name": "Backups", - "next_ping": null, - "pause_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause", - "ping_url": "PING_ENDPOINTf618072a-7bde-4eee-af63-71a77c5723bc", - "status": "paused", - "tags": "prod www", - "timeout": 3600, - "update_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc" -} \ No newline at end of file diff --git a/templates/front/snippets/python_requests_fail.html b/templates/front/snippets/python_requests_fail.html index 37d6ea25..88cb2d4e 100644 --- a/templates/front/snippets/python_requests_fail.html +++ b/templates/front/snippets/python_requests_fail.html @@ -5,9 +5,9 @@ # Do your number crunching, backup dumping, newsletter sending work here. # Return a truthy value on success. # Return a falsy value or throw an exception on failure. - return True + return True -success = False +success = False try: success = do_work() finally: diff --git a/templates/front/snippets/python_requests_start.html b/templates/front/snippets/python_requests_start.html index 0447ee3f..861ccd9d 100644 --- a/templates/front/snippets/python_requests_start.html +++ b/templates/front/snippets/python_requests_start.html @@ -14,7 +14,7 @@ # TODO: run the job here fib = lambda n: n if n < 2 else fib(n - 1) + fib(n - 2) -print("F(42) = %d" % fib(42)) +print("F(42) = %d" % fib(42)) # Signal success: requests.get(URL) diff --git a/templates/front/snippets/update_check_request_a.html b/templates/front/snippets/update_check_request_a.html deleted file mode 100644 index 51ea37d0..00000000 --- a/templates/front/snippets/update_check_request_a.html +++ /dev/null @@ -1,4 +0,0 @@ -
    curl {{ SITE_ROOT }}/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc \
-    --header "X-Api-Key: your-api-key" \
-    --data '{"name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}'
-
    diff --git a/templates/front/snippets/update_check_request_a.txt b/templates/front/snippets/update_check_request_a.txt deleted file mode 100644 index 34907d2d..00000000 --- a/templates/front/snippets/update_check_request_a.txt +++ /dev/null @@ -1,3 +0,0 @@ -curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc \ - --header "X-Api-Key: your-api-key" \ - --data '{"name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}' diff --git a/templates/front/snippets/update_check_request_b.html b/templates/front/snippets/update_check_request_b.html deleted file mode 100644 index 70368b87..00000000 --- a/templates/front/snippets/update_check_request_b.html +++ /dev/null @@ -1,3 +0,0 @@ -
    curl {{ SITE_ROOT }}/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc \
-    --data '{"api_key": "your-api-key", "name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}'
-
    diff --git a/templates/front/snippets/update_check_request_b.txt b/templates/front/snippets/update_check_request_b.txt deleted file mode 100644 index 99e977aa..00000000 --- a/templates/front/snippets/update_check_request_b.txt +++ /dev/null @@ -1,2 +0,0 @@ -curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc \ - --data '{"api_key": "your-api-key", "name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}'