​
Overview

The Health Check endpoint monitors API service availability and infrastructure connectivity. Used for load balancer health checks, monitoring dashboards, and deployment verification.

​
Endpoint

GET /api/health No authentication required - publicly accessible for monitoring.

​
Response Format

​
Healthy Response (200 OK)

{
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "service": "ripplecore-api",
  "version": "1.0.0",
  "environment": "production",
  "checks": {
    "database": {
      "status": "ok"
    },
    "redis": {
      "status": "ok"
    }
  },
  "strictMode": false
}

​
Unhealthy Response (503 Service Unavailable)

{
  "status": "unhealthy",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "service": "ripplecore-api",
  "checks": {
    "database": {
      "status": "error",
      "message": "Connection timeout"
    },
    "redis": {
      "status": "ok"
    }
  }
}

​
Health Checks Performed

​
Database Connectivity

  • Executes SELECT 1 query
  • Verifies PostgreSQL connection
  • Times out after 5 seconds

​
Redis Connectivity

  • Executes PING command
  • Verifies Redis cache availability
  • Times out after 3 seconds

​
Strict Mode

​
Configuration

Set environment variable: STRICT_HEALTH_CHECK=true

​
Behavior

  • Normal Mode (default): Returns 200 OK even with infrastructure issues (logs warnings)
  • Strict Mode: Returns 503 when database or Redis unavailable (prevents unhealthy routing)

​
Use Cases

  • Load Balancers: Use strict mode to automatically remove unhealthy instances
  • Monitoring: Use normal mode for alerting without affecting traffic
  • Development: Normal mode allows testing with partial infrastructure

​
Monitoring Integration

​
HTTP Status Codes

  • 200: Service healthy
  • 503: Service unhealthy (strict mode only)

​
Response Time

  • Healthy: <100ms
  • Warning: 100-500ms
  • Critical: >500ms

​
Alert Conditions

  • HTTP 503 responses
  • Response time >1 second
  • Database connection failures
  • Redis connection failures

​
Deployment Verification

Use the health check to verify successful deployments: 
# Check API health
curl -f https://api.ripplecore.co.uk/api/health

# Check with verbose output
curl -v https://api.ripplecore.co.uk/api/health

# Verify JSON structure
curl https://api.ripplecore.co.uk/api/health | jq .status

​
Load Balancer Configuration

​
Nginx Example

upstream api_backend {
    server api1.ripplecore.co.uk:3002;
    server api2.ripplecore.co.uk:3002;
    server api3.ripplecore.co.uk:3002;
}

server {
    location /api/health {
        proxy_pass http://api_backend;
        proxy_connect_timeout 5s;
        proxy_read_timeout 5s;
    }
}

​
AWS ALB Health Check

Health check path: /api/health
Success codes: 200
Timeout: 5 seconds
Interval: 30 seconds
Unhealthy threshold: 2
Healthy threshold: 2

​
Troubleshooting

​
Common Issues

Database Connection Failed: 
{
  "checks": {
    "database": {
      "status": "error",
      "message": "Connection refused"
    }
  }
}
Solutions:
  • Check PostgreSQL service status
  • Verify connection string
  • Check network connectivity
  • Review database credentials
Redis Connection Failed: 
{
  "checks": {
    "redis": {
      "status": "error",
      "message": "Connection timeout"
    }
  }
}
Solutions:
  • Check Redis service status
  • Verify Redis URL configuration
  • Check network connectivity
  • Review Redis authentication

​
Debug Mode

Enable detailed logging with environment variable: 
DEBUG_HEALTH_CHECK=true
This provides additional diagnostic information in the response.

​
Business Continuity

  • Health checks run independently of application logic
  • No database writes performed during health checks
  • Minimal resource usage (designed for high-frequency polling)
  • Automatic recovery detection when services restore