What is the Health Check API pattern and what should a /health endpoint return?

The Health Check API pattern exposes an HTTP endpoint (typically /health, /actuator/health, or /healthz) that returns the current operational status of a service instance. Load balancers, orchestrators (Kubernetes), and service registries poll this endpoint to determine whether traffic should be routed to an instance and whether it should be restarted.

Two semantically distinct probe types are important (especially in Kubernetes):

• Liveness probe — answers "is this process still alive and not deadlocked?" If it fails, Kubernetes restarts the container. Should only check internal process health — not external dependencies.
• Readiness probe — answers "is this instance ready to serve traffic?" If it fails, the instance is temporarily removed from the load balancer pool (but not restarted). Should check whether all required dependencies (database, downstream services) are reachable.

// Spring Boot Actuator /actuator/health response
{
  "status": "UP",
  "components": {
    "db": {
      "status": "UP",
      "details": { "database": "PostgreSQL", "result": 1 }
    },
    "redis": { "status": "UP" },
    "diskSpace": {
      "status": "UP",
      "details": { "free": 10737418240, "threshold": 10485760 }
    }
  }
}
// Return HTTP 200 when UP; HTTP 503 when DOWN or DEGRADED

Best practices for health endpoints:

• Return a structured JSON body, not just an HTTP status code, so operators can diagnose which dependency is unhealthy.
• Never put liveness and readiness logic in the same endpoint if they have different semantics.
• Keep health checks fast (under 1 second); slow health checks look like outages to the load balancer.
• Include a startup probe for slow-starting services to prevent Kubernetes from restarting them prematurely.

Invest now in Acorns!!! 🚀
Join Acorns and get your $5 bonus!

Acorns is a micro-investing app that automatically invests your "spare change" from daily purchases into diversified, expert-built portfolios of ETFs. It is designed for beginners, allowing you to start investing with as little as $5. The service automates saving and investing. Disclosure: I may receive a referral bonus.

Invest now!!! Get Free equity stock (US, UK only)!

Use Robinhood app to invest in stocks. It is safe and secure. Use the Referral link to claim your free stock when you sign up!.

The Robinhood app makes it easy to trade stocks, crypto and more.

Webull! Receive free stock by signing up using the link: Webull signup.