Express-health-api NPM

Express Health API

npm bundle size

Realtime Health Status API for Node applications with Express framework.

Features:

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

Usage

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

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
Create your custom configurations for the status api Follow here or you can go ahead with default configurations.
Go to your main file where you initialized the express server, and place the line before any middleware or routes.

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

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 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 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.

Response configuration
Property Mandatory Default value Description
statusCodes - true Include status codes of health checks with response
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>
...
```

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

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

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"]
  }
  ...

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

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)

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.