Design API health checks that tell you something useful

Choose the question before the endpoint

A reachable process and a working customer journey are different things. Decide what this monitor should establish: that the server answers, that a critical dependency is ready, or that a safe representative request succeeds. Name the monitor so the team knows which question it answers.

A dedicated read-only endpoint can expose a small readiness result. Keep it cheap enough to call repeatedly, and avoid returning credentials, customer records, internal connection strings or full stack traces. A monitor should observe the service rather than place orders, send emails or modify customer data.

Give the response a small, stable contract

This fictional response reports readiness for a booking API. The application computes ready from the dependencies that are essential to taking bookings. That business decision belongs in your application; UptimeOwl evaluates the field you select.

For this example, choose GET, expected status 200, and a JSON rule: path ready, Must equal, value type True. A response with ready set to false fails that rule even if its HTTP code remains 200. If your endpoint returns 503 when unhealthy, the expected-code rule also catches it.

{
  "ready": true,
  "dependencies": {
    "database": "ok",
    "bookingQueue": "ok"
  }
}

Make exact comparisons intentional

The boolean true differs from the text "true". Choose the matching value type in the editor. Must exist only checks that a field is present, so it would accept ready:false; it is the wrong choice when you need readiness to be true. A missing field, malformed JSON or a response beyond the 64 KiB inspection limit fails the JSON rule.

One monitor supports one JSON field rule. If several conditions define readiness, expose one aggregate boolean from the endpoint, or use separate monitors where separate signals are useful and your plan allows them. A text rule can also be enabled, but all enabled rules must pass along with the HTTP code.

Test the red path before relying on green

Use these cases against a local or staging endpoint you control. The examples are hypothetical; do not break a production dependency to test an alert. A settings review alone cannot show that the endpoint reports a real failure correctly.

1. Confirm HTTP 200 with ready:true passes the intended monitor rule.
2. Change the example body to ready:false while keeping HTTP 200; the result should fail.
3. Try ready:"true" and then omit ready entirely; both should fail the boolean comparison.
4. Return HTTP 503 with ready:true; the HTTP-code rule should still fail.
5. Restore the healthy response and check the recovery confirmation settings.

Keep the boundary clear

Use GET when you need a body rule. HEAD does not provide the JSON body for this check. If the endpoint needs authentication, use UptimeOwl’s protected request settings over HTTPS with a narrowly scoped credential and review redirect behavior.

External HTTP monitoring is a sample from the monitoring service, not a browser transaction, load test or complete view of every region. Combine it with application logs and other observations when assessing impact. Review the endpoint contract whenever the application changes.

Further reading

• Black-box and white-box monitoring — Google SRE