API Health Check Endpoints

Health check endpoints provide a standardized way for infrastructure components (load balancers, container orchestrators, monitoring systems) to determine whether an API instance is operational and ready to serve traffic. Kubernetes defines two types: liveness probes (is the process alive and not deadlocked?) and readiness probes (is the service ready to accept traffic, including its dependencies?). A failed liveness probe triggers a container restart; a failed readiness probe removes the instance from the service's endpoint pool.

A basic health endpoint (GET /health or GET /healthz) returns 200 with a simple status response. A more sophisticated implementation checks dependencies: database connectivity, Redis availability, external API reachability, disk space, and memory usage. The deep health check should return per-dependency status: { status: 'healthy', checks: { database: { status: 'healthy', latency_ms: 5 }, redis: { status: 'degraded', latency_ms: 150 }, disk: { status: 'healthy', free_gb: 42.5 } } }. The overall status is 'healthy' only if all checks pass, 'degraded' if non-critical checks fail, and 'unhealthy' if critical checks fail.

Health check endpoints should not require authentication (they're called by infrastructure components that don't have API credentials), should be lightweight (not triggering expensive operations), and should have their own rate limiting to prevent abuse. The deep health check should include timeouts for each dependency check (e.g., 2 seconds) to avoid the health check itself hanging when a dependency is unresponsive. Caching health check results for a few seconds prevents thundering herd problems when many monitors poll simultaneously.