Health

Rule: Health check operation [hlth-res]

Each REST API SHOULD expose a GET /health operation which returns the availability of the API’s functionality for its clients.

Access to this resource SHOULD be granted to any client of the API.

The payload SHOULD be a JSON object with a property status of type string, that has one of the standardized values below, or a custom value for other API-specific use cases. It SHOULD NOT contain any implementation or infrastructure details for security reasons, unless called by a trusted privileged client.

The HTTP response status SHOULD be either 200 OK when the service is up or partially available, or 503 Service Unavailable when the service is down or out of service.

Clients SHOULD interpret any other HTTP 5xx status, or lack of HTTP response, as the API being unreachable.

Status Status Code Description

UP

200

The API is functioning as expected.

DEGRADED

200

The API is partly unavailable but service can be continued with reduced functionality.

DOWN

503

The API is suffering unexpected failures.
The health status typically depends on the availability of multiple components used to provide the API’s functionality (e.g. application container, database, external web service dependency, …​). It differs from a container liveness status, which only reflects the availability of a single component.
If the health checks triggered by calling GET /health are resource-intensive, API implementations should consider caching the result. This may also protect against denial-of-service (DoS) attacks if the operation can be called from untrusted sources.
Example 1. Service is available
{
  "status": "UP"
}
Example 2. Service is down
{
  "status": "DOWN"
}

When called by a trusted privileged client, the response may contain additional properties with detailed information.

{
  "status": "DOWN",
  "details": {
    "datastore": {
      "status": "DOWN",
      "errorMessage": "connection timeout"
    }
  }
}

The health resource is specified in common-v1.yaml. Note that uppercase is used for the status values, which deviates from [cod-design], in order to align with existing health checks provided by frameworks like Spring Boot and MicroProfile Health. The format of additional component-level details is not specified.