Skip to main content
GET
/
api
/
health
Health API
curl --request GET \
  --url https://api.example.com/api/health
{
  "status": "<string>",
  "timestamp": "<string>",
  "jobQueue": {
    "enabled": true,
    "redis": "<string>"
  }
}

​
Overview

The Health API provides a lightweight endpoint to check the operational status of the BioAgents service, including job queue and Redis connectivity when enabled.

​
No Authentication Required

This endpoint is publicly accessible for monitoring and health checks.

​
GET /api/health

Check service health status.

​
Response Fields

​
status
string
Overall service status:
  • ok: All systems operational
  • degraded: Some systems unavailable but core functionality works
​
timestamp
string
ISO 8601 timestamp of health check
​
jobQueue
object
Job queue status information

​
Examples

​
Example: Healthy Service (Queue Disabled)

curl https://api.bioagents.xyz/api/health
Response: 
{
  "status": "ok",
  "timestamp": "2024-03-15T10:30:45.123Z",
  "jobQueue": {
    "enabled": false
  }
}

​
Example: Healthy Service (Queue Enabled)

curl https://api.bioagents.xyz/api/health
Response: 
{
  "status": "ok",
  "timestamp": "2024-03-15T10:30:45.123Z",
  "jobQueue": {
    "enabled": true,
    "redis": "connected"
  }
}

​
Example: Degraded Service (Redis Unavailable)

curl https://api.bioagents.xyz/api/health
Response: 
{
  "status": "degraded",
  "timestamp": "2024-03-15T10:30:45.123Z",
  "jobQueue": {
    "enabled": true,
    "redis": "disconnected"
  }
}

​
Use Cases

​
Kubernetes Liveness Probe

livenessProbe:
  httpGet:
    path: /api/health
    port: 3000
  initialDelaySeconds: 30
  periodSeconds: 10
  timeoutSeconds: 5
  failureThreshold: 3

​
Docker Compose Health Check

services:
  bioagents:
    image: bioagents:latest
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

​
Monitoring Script

#!/bin/bash
# health-check.sh

RESPONSE=$(curl -s https://api.bioagents.xyz/api/health)
STATUS=$(echo $RESPONSE | jq -r '.status')

if [ "$STATUS" != "ok" ]; then
  echo "Service degraded: $RESPONSE"
  # Send alert to monitoring system
  curl -X POST https://monitoring.example.com/alert \
    -H "Content-Type: application/json" \
    -d "{\"service\": \"bioagents\", \"status\": \"$STATUS\", \"details\": $RESPONSE}"
fi

​
JavaScript Health Monitor

async function checkHealth() {
  try {
    const response = await fetch('https://api.bioagents.xyz/api/health');
    const health = await response.json();
    
    if (health.status !== 'ok') {
      console.warn('Service health degraded:', health);
      
      // Check specific subsystems
      if (health.jobQueue?.enabled && health.jobQueue?.redis === 'disconnected') {
        console.error('Redis connection lost - queue jobs may fail');
      }
    }
    
    return health;
  } catch (error) {
    console.error('Health check failed:', error);
    return { status: 'unreachable', error: error.message };
  }
}

// Poll every 30 seconds
setInterval(checkHealth, 30000);

​
Status Interpretation

​
ok Status

  • Core API endpoints are operational
  • Database connectivity is working
  • If queue enabled: Redis is connected
  • Ready to accept requests

​
degraded Status

  • Core API may still work
  • Redis connection failed (if queue enabled)
  • Queue-based endpoints will return 503 errors
  • In-process mode endpoints continue working

​
No Response

  • Service is down or unreachable
  • Network connectivity issues
  • Server crashed or not started

​
Implementation Details

​
Queue Disabled (USE_JOB_QUEUE=false)

  • Health check always returns ok (no external dependencies)
  • Response time: ~1-5ms

​
Queue Enabled (USE_JOB_QUEUE=true)

  • Performs Redis PING to verify connectivity
  • Response time: ~10-50ms (depends on Redis latency)
  • If Redis unavailable, sets status to degraded

​
Endpoint Location

Defined in src/index.ts:212-251 
.get("/api/health", async () => {
  const health = {
    status: "ok",
    timestamp: new Date().toISOString(),
  };

  if (isJobQueueEnabled()) {
    try {
      const redis = getBullMQConnection();
      await redis.ping();
      health.jobQueue = {
        enabled: true,
        redis: "connected",
      };
    } catch (error) {
      health.jobQueue = {
        enabled: true,
        redis: "disconnected",
      };
      health.status = "degraded";
    }
  } else {
    health.jobQueue = {
      enabled: false,
    };
  }

  return health;
})

​
Monitoring Best Practices

  1. Set up automated health checks every 30-60 seconds
  2. Alert on degraded status - indicates Redis issues
  3. Alert on consecutive failures (3+ in a row) - service may be down
  4. Monitor response times - slow responses indicate resource constraints
  5. Check logs when health degrades - look for Redis connection errors

​
Example Alert Rules

# Prometheus alerting rules
groups:
  - name: bioagents
    rules:
      - alert: BioAgentsServiceDown
        expr: up{job="bioagents"} == 0
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "BioAgents service is down"
          
      - alert: BioAgentsServiceDegraded
        expr: bioagents_health_status{status="degraded"} == 1
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "BioAgents service degraded (Redis disconnected)"
          
      - alert: BioAgentsSlowHealthCheck
        expr: bioagents_health_check_duration_seconds > 1
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Health check taking longer than 1 second"

Build docs developers (and LLMs) love

Get started for freeTalk to us