Use Health Checks and the Health Endpoint

Data API builder provides a /health endpoint to monitor the responsiveness and health of your API’s data sources and entities. This endpoint runs checks against all configured data sources, REST endpoints, and GraphQL entities, validating that they respond within thresholds you set.

How health checks work

• For each data source, a simple database-specific query verifies connectivity and measures response time.
• For each entity (REST or GraphQL), a query without predicates runs, returning the first N rows to confirm responsiveness.
• The /health endpoint aggregates these results into a comprehensive report indicating overall health.

Runtime health configuration

Health checks are controlled in the runtime.health section, which configures the global health endpoint:

Example runtime health configuration

{
  "runtime": {
    "health": {
      "enabled": true,
      "roles": ["admin", "monitoring"],
      "cache-ttl-seconds": 10,
      "max-query-parallelism": 4
    }
  }
}

Roles behavior

• When host.mode is development, the health endpoint is accessible to everyone without requiring roles; all calls are treated as anonymous.
• When host.mode is production, roles must be explicitly defined to access the comprehensive health endpoint. Omitting roles disables access except for anonymous if specified.
• Multiple roles can be included in the roles array.
• The roles here do not override the roles' permissions for API or GraphQL access. If a role lacks permission to execute an endpoint or query, the health check will reflect a failure.
• At the root path /, a basic health endpoint is always available to everyone with limited information and no health checks.

Data source health configuration

Each data source can be configured for health checks individually in data-source.health:

Example:

{
  "data-source": {
    "health": {
      "enabled": true,
      "name": "primary-sql-db",
      "threshold-ms": 1500
    }
  }
}

Entity health configuration

Health checks can also be enabled per entity in entities.{entity-name}.health:

Example:

{
  "entities": {
    "Book": {
      "health": {
        "enabled": true,
        "first": 3,
        "threshold-ms": 500
      }
    }
  }
}

Additional considerations

• The health check cache prevents repeated rapid requests from overwhelming the system by caching the health report for the configured TTL.
• Max query parallelism controls concurrency of checks to speed execution without overloading resources; use this value with care.
• The root / health endpoint provides minimal info with no checks and is always publicly accessible.
• Health check failures respect entity and endpoint authorization — lack of permission results in failure reports, consistent with DAB’s security model.