How Would You Create a Public API Health Check?
From the earlier reference collection. Read the current software blog.
A small health-check client can report the HTTP response, elapsed time, media type, and whether the body parses as expected.
Define the endpoint and expected response
A public API health check makes one request and reports what happened. Its result should separate the HTTP status, request latency, response content type, and body parse outcome. A successful network request does not necessarily mean the endpoint returned useful data, so each observation deserves its own field.
Start with a configured URL and request timeout. Make the expected format explicit, such as JSON, and avoid sending credentials unless the API’s documentation requires them and the user has configured them. A health check should not infer undocumented endpoints or treat a generic server response as valid application data.
Measure the request honestly
Record a start time immediately before the request and an end time when the response arrives or fails. Report the elapsed duration in milliseconds, while labeling it as client-observed latency; it includes network and client behavior, not just server processing. Apply a finite timeout so an unavailable service does not leave the command hanging indefinitely.
Capture the HTTP status code and response content type even when the status is an error. Handle DNS, connection, timeout, and TLS failures as request errors with concise details. Do not report an absent response as status zero; say that no HTTP response was received.
Check parsing separately
If the content type indicates JSON or JSON is the configured expectation, attempt to parse the body and report success or failure. Parsing success only means the document is syntactically valid. If the application contract requires a field such as items, make that a separate optional assertion and explain which condition failed.
For example, a response could have status 200 and a JSON content type but contain malformed JSON. The report should preserve all three facts: HTTP success, observed media type, and parse failure. A text error page with a 503 status should likewise remain visible as an HTTP error rather than being reduced to “parse failed.”
Keep results stable and actionable
Print one structured result that can be read by a person or consumed by automation. A command might exit successfully only when the request completed, returned an accepted status, and passed the configured parse check. Keep the policy configurable, since some APIs use other successful status codes or response types.
Run the check manually against a known endpoint and against an intentionally incorrect path to see both normal and error reporting. Avoid high-frequency polling that could burden a public service; use a sensible interval and respect any published usage guidance. The output should let an operator identify whether the issue is connectivity, HTTP behavior, media type, or content parsing.