Skip to main content

Implementing Health Check Handler

This describes the requirements of the health-check handler that the provider must implement.

Because there are many frameworks available for web-based applications and services, we will first describe the requirements of the end-point implementation at a framework-independent level

Health-check failure#

A health-check failure one of these scenarios:

  • Failure to respond within 10 seconds
  • The HTTP response does not have a HTTP 200 status code.
  • The HTTP content-type is not application/json.
  • The HTTP content body is not the correct JSON object. See below for the JSON object shape.

Word-based description#

The health-check handler must:

  • Be located at <baseUrl>/service/healthCheck.
  • Accept HTTP POST requests with Content-Type of application/json.

The leading portion <baseUrl> is configured thru the API Administration UI.

While a service-provider capability is enabled, this endpoint will recieve a HTTP POST request on a 5 minute interval. The request body will contain a JSON object with three properties: id, name, and timestamp.

The health-check endpoint should handle the request with the following HTTP response:

  • HTTP status code 200
  • The response headers should include Content-Type: application/json
  • The response body should be a JSON object.
    • It should have two properties: id and name.
    • The response's id value should mirror the request's id value.
    • The response's timestamp value should be populated with the current UTC time at the client.

These requirements on the health-check endpoint are also specified in the REST API reference.

Code Snippets with TypeScript and Node.js#

These are code snippets to assist when manually implement the health-check endpoint with TypeScript and Node.js.

Request and Response Types#

First, define a type that defines the structure of the response body.

export interface HealthCheckResponse {  id: string;  timestamp: Date;}

Second, define a type that defines the structure of the request body.

export interface HealthCheckRequest {  id: string;  name: string;  timestamp: Date;}

Routing and Controller#

Next, pick your favorite framework that is compatible with node's routing-controllers. See the routing-controller project

Finally, define a route using node's routing-controllers

  @Post('/service/healthCheck')  async handleHealthCheckRequest(    @Body() requestBody: HealthCheckRequest,  ): Promise<HealthCheckResponse> {    return Promise.resolve({      id: requestBody.id,      timestamp: new Date(new Date().toUTCString()),    });  }

And that's it for the implementation of the health-check endpoint.