API monitoring: check that your API works, not just that it responds

A basic uptime check asks one question: did the server answer? For an API, that's not nearly enough. An endpoint can return 200 OK with an error message in the body, an empty list where there should be data, or a stale value from a cache that stopped updating hours ago. Your monitoring says green; your customers' integrations are failing.

Real API monitoring checks that the API works: that it returns the right data, in the right shape, fast enough.

“Up” versus “working”

Here's a response that passes any status-code check:

HTTP/1.1 200 OK

{
  "status": "degraded",
  "data": { "orders": [] },
  "error": "database read replica unavailable"
}

Plenty of frameworks and gateways return 200 for errors like this. To catch it, the monitor has to read the body and check specific values.

What to check

1. The status code you expect

Not just “any success”: if creating a resource should return 201, check for 201. A different code means the behaviour changed.

2. Values in the response body

Assertions on the JSON are where API monitoring earns its keep. Useful ones:

3. Response time

A payment API that takes 9 seconds is, for its callers, broken. Watch response time over time; a steady climb usually comes before an outage.

4. Authentication

Monitor authenticated endpoints too, with a dedicated read-only API key sent as a header. Expired keys, broken token validation and permission bugs only show up on authenticated requests.

Design a health endpoint worth monitoring

A /health endpoint that always returns {"status":"ok"} without checking anything is the most common false sense of security. A useful one checks the things your API needs, quickly, and says which part failed:

{
  "status": "ok",
  "checks": {
    "database": "ok",
    "cache": "ok",
    "queue": "ok"
  },
  "version": "2.4.1"
}

• Keep it fast: each dependency check should be a trivial query with a short timeout.
• Return a non-200 status (such as 503) when a critical dependency is down, and say which one in the body.
• Don't expose secrets, hostnames or stack traces: the endpoint is often public.
• Then monitor it with assertions on each check, e.g. checks.database equals "ok", so the alert tells you what broke.

Setting up an API monitor in Spot Downtime

API monitors are included in every plan, including Free:

1. Choose Add monitor → API and enter the URL.
2. Pick the method (GET, POST, PUT, PATCH, DELETE or HEAD), add up to 20 headers (like an Authorization header) and, if needed, a request body.
3. Optionally set the exact status code to expect. Without one, any 2xx or 3xx counts as success.
4. Add up to 20 assertions on the JSON response. Paths use dot or bracket notation, like data.items[0].id, and .length works on lists and strings. Operators: equals, not equals, contains, exists, not exists, greater than, less than.

Every failure is retried once after 2 seconds before it counts, and the alert includes which assertion failed, so you know where to look before you open a laptop. See the details on the API monitoring page.

A few practical tips

• Use test data that never changes. Assert on a fixed test record (a known product or a test account) rather than live data that can legitimately change.
• Be careful with writes. A POST monitor runs every minute or so. Point it at an idempotent endpoint, or a test mode that doesn't create real orders, emails or charges.
• One monitor per critical flow. Separate monitors for login, search and checkout make alerts specific.
• Watch third-party APIs you depend on. If your product breaks when a payment or shipping API breaks, monitor their endpoints too, so you know whose problem it is in seconds.

Create a free account and set up your first API monitor in a couple of minutes. Pair it with a heartbeat for the background jobs behind it.