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.