API Monitoring

Why APIs need their own monitoring

An API isn't just a website behind /api/. It's a contract. The HTTP method matters - GET vs POST changes meaning. Headers carry authentication, content negotiation, idempotency keys. The request body is the input. The response code is meaningful (a 401 vs 403 vs 422 each tell different stories). The response body has structure - JSON paths your integrators rely on. A regular uptime check that just hits a URL with GET will miss most of the ways an API can break: a malformed JSON response that still returns 200, an authentication endpoint that started accepting wrong credentials, a webhook that broke its payload schema, an endpoint that returns 200 but with a "status": "error" inside.

API monitoring solves this by giving you control over every part of the request and every part of how the response is verified. You configure exactly the call your integrators make - same method, same headers, same body, same auth - and exactly what success means - exact status codes, JSON path values, response time thresholds, response size bounds.

Configuring the request

For each API monitor in DiagnoSEO Uptime Monitoring, you can configure:

• HTTP method: GET, POST, PUT, PATCH, DELETE, HEAD. Pick whatever your integrators use.
• Custom headers: as a JSON object, e.g. {"Authorization": "Bearer eyJ...", "X-API-Version": "2024-01-15"}. Standard for testing OAuth, JWT, API keys, content negotiation, custom protocols.
• Request body: any string - JSON, XML, form-encoded, plain text. Sent for POST/PUT/PATCH/DELETE.
• Basic auth: username and password if you're protecting the endpoint that way.
• Expected status codes: list or range. Default is 200-399, but you can tighten to a single code (e.g. exactly 201 for a creation endpoint) or allow specific others (e.g. 200,202,204).

The check follows up to 5 redirects, gzip-decodes the body, and parses Content-Type to detect JSON. Each check records the actual status code, response time, response size and any error. Multiple consecutive failures (configurable, default two) trigger an incident.

JSON path assertions

Status codes alone aren't enough for many APIs. A health check endpoint can return 200 with a body of {"status": "degraded", "db": "down"} - still 200, but you absolutely want to know. A pricing API can return 200 with a body where data.price dropped to null. A search API can return 200 with results: [] when its index is broken.

For these cases, configure a JSON path assertion. Set the path (e.g. data.status or health.checks.db) and the expected value (e.g. healthy, true, or a specific number). On every check, the response is JSON-decoded and the value at that path is compared. Mismatch fails the check, regardless of HTTP status.

Path syntax is dot notation with bracket support: data.items[0].id works, as does users.john.email. The asserted value is compared as a string, so "true" matches a boolean true, and numbers match either as strings or numbers.

Authentication patterns

The two most common auth styles work out of the box. For Bearer tokens (OAuth, JWT, API keys), use the headers field: {"Authorization": "Bearer eyJhbGciOi..."}. The token sits in your monitor config and is sent on every check. For basic auth, use the dedicated username/password fields - they're stored and combined into the standard header.

If your auth requires per-request signing or a token refresh, that's harder. Two reasonable patterns: (1) configure a long-lived service account token specifically for monitoring, or (2) expose an unauthenticated health endpoint that mirrors the real auth-protected one's status, and monitor that. Most modern APIs ship something like that already.

Patterns we recommend

• One monitor per critical endpoint. Don't try to test every endpoint - pick the 5-10 that, if broken, would cause real damage.
• Use exact status codes. Default 200-399 is too permissive for an API. A creation endpoint should return exactly 201; a successful idempotent endpoint exactly 200; an authentication endpoint exactly 200 (success) or 401 (well-formed failure - not 500).
• Pair status with JSON assertion. The combination catches both transport-layer and content-layer regressions. Status alone misses content errors; JSON assertion alone is fragile if the API redirects.
• Set a response time threshold. APIs degrading is a leading indicator of dependency issues. A monitor configured with rt_threshold_ms = 800 tells you the API is slow before it fully fails.
• Keep request bodies small. The check happens every minute - large bodies waste bandwidth on both sides. A representative-but-minimal payload is enough.

Combine with other monitor types

For each API endpoint, an API monitor verifies the call works. A separate ping or port monitor verifies the underlying host is alive. An SSL/domain check on the same hostname catches certificate and registration issues. The DNS sub-monitor watches for record changes that could indicate a hijack. Together, four monitors per API give you full-stack confidence with very little overlap.

Setup

Open the tool, click "Add monitor", choose type "API". Paste the URL. Open the Advanced section. Pick the method, paste headers as JSON, paste the request body if needed, set basic auth if used, type expected codes (e.g. 200 or 200,201). Add the JSON path assertion if applicable. Set interval and confirmation period. Save. From the next cycle the monitor calls your API exactly the way an integrator would, validates the response and alerts the moment something regresses.

Frequently asked questions

• What HTTP methods can I use for API monitoring?

  GET, POST, PUT, DELETE, PATCH, and HEAD. Configure the method per monitor — for write endpoints (POST/PUT/PATCH) the request body is also configurable as a JSON string or form data.

• How do JSON assertions work?

  You provide a JSON path (e.g. data.status or results[0].id) and an expected value. The monitor fetches the response, parses it as JSON, extracts the path, and compares against the expected value. If they don't match, the check fails with an "assertion failed" error showing the actual value.

• Can I send authentication headers?

  Yes. Custom HTTP headers are configurable per monitor — Authorization tokens, API keys, content-type, anything. Header values are encrypted at rest in the database. For Basic Auth, there's a dedicated username/password field that signs the request automatically.

• What if my API returns 200 with an error payload?

  Common pattern: API returns HTTP 200 but the body says {"status":"error"}. A naive uptime monitor thinks this is healthy. Use JSON assertion status == "ok" to catch it — the assertion fails and the monitor reports DOWN even though HTTP says 200.

• How do I handle rate-limited APIs?

  Set the check interval to respect the API's rate limit (e.g. 5-minute interval if the API allows 12 calls/hour). The monitor counts as one API call per check from one geographic region. Multi-region checks multiply the call count — use single-region if your API has tight limits.