Health API

Health check endpoints for monitoring and load balancing.

Endpoints

Health Check

Returns the current health status of the API.

GET /api/health

Success Response 200 OK

{
  "status": "healthy",
  "timestamp": "2026-01-12T10:00:00Z",
  "version": "1.0.0"
}

Unhealthy Response 503 Service Unavailable

{
  "status": "unhealthy",
  "timestamp": "2026-01-12T10:00:00Z",
  "version": "1.0.0",
  "checks": {
    "database": "unhealthy",
    "redis": "healthy"
  }
}

---

Readiness Check

Checks if the service is ready to receive traffic.

GET /api/health/ready

Success Response 200 OK

{
  "status": "ready",
  "timestamp": "2026-01-12T10:00:00Z"
}

Not Ready Response 503 Service Unavailable

{
  "status": "not_ready",
  "timestamp": "2026-01-12T10:00:00Z",
  "reason": "Database connection not established"
}

---

Liveness Check

Checks if the service is alive (for Kubernetes liveness probes).

GET /api/health/live

Success Response 200 OK

{
  "status": "alive",
  "timestamp": "2026-01-12T10:00:00Z"
}

---

Kubernetes Configuration

apiVersion: v1
kind: Pod
spec:
  containers:
    - name: vulcan-api
      livenessProbe:
        httpGet:
          path: /api/health/live
          port: 8080
        initialDelaySeconds: 10
        periodSeconds: 10
      readinessProbe:
        httpGet:
          path: /api/health/ready
          port: 8080
        initialDelaySeconds: 5
        periodSeconds: 5

Usage

The health endpoints are used for:

1. Load Balancer Health Checks - Route traffic only to healthy instances
2. Kubernetes Probes - Restart unhealthy pods, prevent traffic to unready pods
3. Monitoring Dashboards - Track service health over time
4. Alerting - Trigger alerts when services become unhealthy