Health Check Response Format for HTTP APIs

I'm continuing my journey on getting more familiar with HTTP APIs by reading related Request For Comments. This time, I read the on the suggestion of . In this post, I'd like to summarize my reading. Health Check Response Format for HTTP APIs Stefano Fago Note that it's a draft. Moreover, it has been dormant for nearly two years and, thus, has been automatically expired. However, it's the closest to a specification on health checks and thus deserves some love. Sample data visualization Even though it's not a long read, it's a bit "dry". Fortunately, the specification offers a JSON sample. I copy-pasted it in PlantUML, and presto, it shows a visual representation of it: Let's have a look at the proposed structure element by element. The root object At its simplest, the response is a JSON object with a mandatory property: status Values can be: for healthy status. The value can also be (for NodeJS) and (for Spring Boot) to account for existing health check libraries. The HTTP status code must be in the range from 2xx to 3xx. pass ok up for healthy status but with concerns with the same HTTP status range. warn to indicate unhealthy status. Possible alternative values include (NodeJS) and (Spring Boot). The HTTP status code must be in the range from 4xx to 5xx. fail error down One can add additional values: optional : version of the service version public : internal version of the service. For example, the would be incremented for non-compatible change, while the could be the commit hash or a semantic version. releaseId version releaseId : the unique identifier of the service serviceId : self-explanatory description : array of non-structured notes notes : plain error message in case of or . The field should be left blank for . output pass warn pass The objects links The object consists of object pairs. Values are URIs, while keys can be URIs or common/registered ones: see for common values, , . links RFC5988 e.g. self The objects checks Keys of objects consist of two terms separated by a colon, component name, and measurement name. The latter can be either: checks A pre-defined value: , , , or utilization responseTime connections uptime A standard term from a well-known source, , IANA, , etc. e.g. microformat.org An URI Values consist of one of the following keys: : unique id of this component componentId : componentType A pre-defined value, , , or component datastore system A standard term from a well-known source, , IANA, , etc. e.g. microformat.org An URI : any valid JSON value observedValue : unit of measurement observedUnit : as the parent object's status, but for this component, only status : if the component is not , lists all affected endpoints affectedEndpoints pass : date-time in ISO8601 format of the observation time : as the parent object's output, but for this component, only output : see the previous section links Any other non-standard value I tried implementing the above with Spring Boot using a custom . Here's the best I could come up with: HealthIndicator The current structure of the JSON response needs to be (easily?) customizable. You'd need to create your endpoint. I hope the Spring Boot team provides the option to generate a compatible structure. Conclusion The Healthcheck IETF draft is a great initiative to standardize health checks across the industry. It would allow monitoring tools to rely on HTTP status and response body without ad-hoc configuration on each service. Unfortunately, the draft is expired because of a lack of activity. I'd love to see it revived, though. To go further: Health Check API "Spring Boot Actuator: Health" Originally at on May 28th, 2023 published A Java Geek