Skip to content
Go to dashboard

2.3API

What it checks#

An API monitor sends one HTTP request and checks the response, like a URL monitor. It has the same form and the same assertions. It can also use team secrets. A team secret is a saved password or token that you refer to by name (chapter 8). Your plan must include API monitors.

When it is up, degraded or down#

  • Up, degraded and down work as for a URL monitor (2.2).
  • A secret that cannot be sent makes the check down. Examples: secret NAME has no allowed sites, secret NAME is only sent over https, secret NAME is not allowed on <host>.
  • A redirect to a site the secret is not allowed on is not followed: redirect not followed: secret NAME is not allowed on <host>.

Configuration#

The fields and defaults are the same as for a URL monitor (2.2). The form adds this hint: Write ${NAME} in the URL, a header value or the body to use a team secret. It is sent only over https to the secret's allowed sites.

Dashboard fieldDefaultLimits and notes
nameEmptyRequired. Up to 200 characters, on one line.
check interval60 secondsAt least 1 second. Your plan's minimum interval still applies: below it the form shows Your plan checks at most every N seconds.
timeout10 secondsIn seconds. A value above 60 seconds counts as 60 seconds.
locationsNone (runs from us-west)Choose from the regions shown. The check runs from each one you pick.
on failure — notifyNone (all team channels)Pick channels to limit who is alerted. Shown only when your team has channels.
request (method, URL)GET, emptyAs for URL. The URL may contain ${NAME}.
headersNoneUp to 50. Values may contain ${NAME}.
bodyEmptyMay contain ${NAME}.
assertionsstatus_code eq 200Every assertion must pass. Up to 50.

Assertions supported#

The same as URL monitors (2.2). json_schema checks the whole JSON body against a JSON Schema. It works on URL, API and multi-step API monitors only.

Example#

Call an orders endpoint with a token saved as the team secret ORDERS_API_TOKEN. Check the shape of the reply.

FieldValue
requestGET https://api.acme.io/v1/orders
headersAuthorization : Bearer ${ORDERS_API_TOKEN}
assertionsstatus_code eq 200
json_schema with the schema below
JSON Schema
json
{
  "type": "object",
  "required": ["id"],
  "properties": {"id": {"type": "integer"}}
}
Through the API (CreateApiMonitor)
bash
API=https://www.obsrvly.com/api/gw/monitor/obsrvly.v1.MonitorConfigService
curl -s "$API/CreateApiMonitor" \
  -H "Authorization: Bearer $OBSRVLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "orders",
  "url": "https://api.acme.io/v1/orders",
  "headers": {"Authorization": "Bearer ${ORDERS_API_TOKEN}"},
  "intervalSeconds": 60,
  "assertions": [
    {"type": "status_code", "op": "ASSERTION_OP_EQ", "value": "200"},
    {"type": "json_schema",
     "value": "{\"type\":\"object\",\"required\":[\"id\"]}"}
  ]
}'

Without a plan that includes API monitors, the call fails with plan does not allow this monitor type: API monitors require Pro or Business.

Good to know#

  • A secret is sent only over https, and only to the sites you allowed for it (chapter 8).
  • Messages show ${NAME}, never the secret's value.
  • If a secret cannot be used at all, the result is could not run, with a message that starts secret NAME cannot be used.
  • To create many API monitors at once from an OpenAPI spec, see 2.15.

Last updated