Express Health API

Realtime Health Status API for Node applications with Express framework.

Table of contents

1. Features
2. Usage
3. Custom Health Status Configuration
   1. Main parts of the configurations
   2. Custom configuration properties
      1. Response configuration
      2. API Security configuration
      3. System Information configuration
      4. Consumed services configuration
      5. API's configuration
      6. Example custom configuration
4. Example Server
5. Contributions
6. Development
7. License

Features:

1. /status api to serve the health statuses
2. Custom configurations to customize your health API
3. Include CPU, Memory, Custom services(e.g: Docker) Load, Request and Response statistics with health API
4. Attach status of the dependent services/consumed services with your health API
5. Customize your server API statuses with dependent services/consumed services
6. Secure your health endpoint before exposing your server related details

Usage

Supports to Node.js versions 8.x and above.

1. Install the dependency to your Node.js project by using any of the following commands,
   • NPM : npm install express-health-api --save
   • Yarn : yarn add express-health-api
2. Create your custom configurations for the status api [Follow here] or you can go ahead with default configurations.
3. Go to your main file where you initialized the express server, and place the line before any middleware or routes.

const app = express(); // create express server

const expressHealthApi = require('express-health-api');
app.use(expressHealthApi())

4. Start your server and go to the health API endpoint (default: <your_server_address>/status)

---

Custom Health Status Configuration

You can customize the health API for your needs, and this will send the response based on those custom configurations.

const app = express(); // create express server

const expressHealthApi = require('express-health-api');
app.use(expressHealthApi({ apiPath: "/health" } ))

Or, you can create configuration file for HealthAPI and attach it with the initialization method,

1. Create a custom configuration file in your project (e.g: /src/config/healthApi.config.json)
2. Import that configuration file to your main file, and pass the configuration to expressHealthApi initiation.

const app = express(); // create express server

const expressHealthApi = require('express-health-api');
const customHealthApiConfiguration = require('./config/healthApi.config.json')
app.use(expressHealthApi(customHealthApiConfiguration))

Main parts of the configurations

Property	Mandatory	Default value	Description
apiPath	-	"/status"	API path name
apiSecurity	-	false	Secure health API with auth token
response	-	{ Object with all true }	Response object customization (You can avoid unwanted properties from health API response)
systemInformation	-	{ Object with all true }	Customize required system information properties
consumedServicesAsyncMode	-	true	Consumed services health check method(Async or Sync based requests to endpoints)
consumedServices	-	{ }	Configuration of all the consumed services
apis	-	{ }	Configuration of all available APIs in the server

Custom configuration properties

Follow the steps to create your custom configuration file for health API.

1. Response configuration

   Property	Mandatory	Default value	Description
   statusCodes	-	true	Include status codes of health checks with response

2. API Security configuration

   You can use this property to secure your health API if you don't want to expose all of your data outside. You can enable API Security with header token,

   ...
   "apiSecurity": { "authToken": "YOUR_TOKEN" }
   ...

   Property	Mandatory	Default value	Description
   authToken	✓	Disable API Security	Token to restrict the unauthorized access to your health API

   when you enable API Security for health API,

   • You have to attach auth-token to the request header to access the health API

     curl -i -H "auth-token:1234567" "http://localhost:5000/status"

   • Health API requests without valid auth-token in header will get the following response (anyway it will send 200 - Success response)

       Response Status: 200
       Response: {
         "status": "up",
         "error": {
           "code": "AUTH_TOKEN_REQUIRED",
           "message": "Authentication required"
         }
       }

   If you like to have different AUTH_TOKEN for each environment, you can update the AUTH_TOKEN through ENV properties.

   • Add HEALTH_API_AUTH_TOKEN to your .env file or ENV properties

     ...
     HEALTH_API_AUTH_TOKEN=<your_token>
     ...
     

3. System Information configuration

   Property	Mandatory	Default value	Description
   systemInformation	-	{ Object with all true }	Customize the system related information
   ── common	-	true	Retrieve common(OS, Uptime) information
   ── cpu	-	true	Retrieve CPU(Cores, Speeds) information
   ── memory	-	true	Retrieve memory(Total, Free) information
   ── services	-	undefined	Retrieve running service information from the server (Array of process names)

   This is the example configuration to configure required system information,

     ...
     "systemInformation": {
       "common": true,
       "cpu": true,
       "memory": true,
       "services": ["mysql", "apache2", "docker"]
     }
     ...

4. Consumed services configuration

   Structure should follow this pattern : { serviceId: { ...service object } }. Service object properties are,

   Property	Mandatory	Default value	Description
   serviceName	-	Unknown service name	Name to indicate the consumed service
   healthCheckUrl	✓	-	Health check endpoint of the service
   requestMethod	-	GET	Request method of the health check URL (GET/POST/PUT/PATCH/HEAD/DELETE)
   expectedResponseStatus	-	200	Expected response status code from the health check endpoint

5. API's configuration

   Structure should follow this pattern : { apiId: { ...api object } }. API object properties are,

   Property	Mandatory	Default value	Description
   api	-	Unknown API name	Name to indicate the API in the server
   requestMethod	-	GET	Request method of the API (GET/POST/PUT/PATCH/HEAD/DELETE)
   dependsOn	-	{ }	Services configuration which this API depends on
   ── serviceId	✓	-	ServiceId which mentioned in the consumed services section
   ── isRequired	-	true	Is this service required to serve this API (down this API if this service went down)

6. Example custom configuration

   {
     "apiPath": "/status",
     "response": {
       "statusCodes": true,
     },
     "systemInformation": {
       "common": true,
       "cpu": true,
       "memory": true,
       "services": ["mysql", "apache2"]
     },
     "consumedServicesAsyncMode": false,
     "consumedServices": {
       "mockService1": {
         "serviceName": "Mock Service 1",
         "healthCheckUrl": "https://sampleHealthcheckUrl-1",
         "requestMethod": "GET",
         "expectedResponseStatus": 200
       }
     },
     "apis": { 
       "getUser": {
         "apiName": "Get Users",
         "requestMethod": "GET",
         "dependsOn": [
           {
             "serviceId": "mockService1",
             "isRequired": true
           }
         ]
       },
     }
   }

   Minimal custom configuration would be simple as this(you can ignore other properties as those will be filled with default values through the process),

   {
     "consumedServices": {                 
       "mockService1": {                   
         "serviceName": "Mock Service 1",  
         "healthCheckUrl": "https://sampleHealthcheckUrl-1",
       },
       "mockService2": {                   
         "serviceName": "Mock Service 2",  
         "healthCheckUrl": "https://sampleHealthcheckUrl-2",
       }
     },
     "apis": {                             
       "getUser": {                        
         "apiName": "Get Users",           
         "dependsOn": [{ "serviceId": "mockService1" }]
       },
       "getAddress": {                        
         "apiName": "Get Address",           
         "dependsOn": [{ "serviceId": "mockService1" }, { "serviceId": "mockService2" }]
       },
     }
   }

   Find the test-server custom configurations here as an example.

Example Server

This project has an example project configured with custom configurations. To run that project and see the outputs follow these steps,

1. Clone this repository : git clone https://github.com/RafalWilinski/express-status-monitor
2. Go inside the test-server folder : cd express-status-monitor/test-server
3. Install the required dependencies : npm install or yarn
4. Start the server : npm start or yarn start
5. Go to https://localhost:5000/status and get the experience of express-health-api.

Contributions

You can add any suggestions/feature requirements/bugs to the Github issues page : https://github.com/apisquare/express-health-api/issues

Add your fixes and development changes as pull requests to this repository.

Development

Folder structure of the project,

├── docs                    # Documentation files
├── src                     # Source files
├── test                    # Project tests
├── test-server             # Example server project
├── .nycrc                  # Coverage configurations
├── .index.js               # Main exported file
└── README.md

• To run the test cases: npm test or yarn test
• To get the coverage of the project: npm coverage or yarn coverage
• To get the lint issues in the changes: npm lint or yarn lint
• To fix your lint issues: npm lint:fix or yarn lint:fix

This project is configured to validate the test cases and lint issues before each commit. So don't bypass the commit with any issues in your changes.

License

MIT License