Health Checks

Monitor API health and readiness

Health Check Endpoints

Monitor the API’s health, readiness, and liveness for deployment orchestration and monitoring.

Endpoints Overview

Endpoint	Purpose	Use Case
/health	Legacy health check	Basic monitoring
/ready	Readiness probe	Kubernetes readiness
/live	Liveness probe	Kubernetes liveness

GET /health

Legacy health endpoint that returns basic API status.

Request

curl https://api.gtmapis.com/health

Response (200 OK)

{
  "status": "healthy",
  "timestamp": "2025-01-02T10:30:00Z"
}

GET /ready

Kubernetes readiness probe that performs comprehensive service checks.

What It Checks

• Redis connection and availability
• Database connection (when enabled)
• DNS resolution capability
• SMTP connectivity
• API service health

Request

curl https://api.gtmapis.com/ready

Response (200 OK)

When all services are ready:

{
  "status": "ready",
  "checks": {
    "redis": "ok",
    "dns": "ok",
    "smtp": "ok"
  },
  "timestamp": "2025-01-02T10:30:00Z"
}

Response (503 Service Unavailable)

When one or more services are unhealthy:

{
  "status": "not_ready",
  "checks": {
    "redis": "failed",
    "dns": "ok",
    "smtp": "ok"
  },
  "errors": [
    "Redis connection failed: connection refused"
  ],
  "timestamp": "2025-01-02T10:30:00Z"
}

Kubernetes Configuration

readinessProbe:
  httpGet:
    path: /ready
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 10
  timeoutSeconds: 5
  successThreshold: 1
  failureThreshold: 3

GET /live

Kubernetes liveness probe for basic alive status.

What It Checks

• API service is running
• HTTP server is responsive
• No deadlocks or hangs

Note: This is a lightweight check that doesn’t verify dependencies

Request

curl https://api.gtmapis.com/live

Response (200 OK)

{
  "status": "alive",
  "timestamp": "2025-01-02T10:30:00Z"
}

Kubernetes Configuration

livenessProbe:
  httpGet:
    path: /live
    port: 8080
  initialDelaySeconds: 30
  periodSeconds: 30
  timeoutSeconds: 5
  successThreshold: 1
  failureThreshold: 3

Best Practices

Monitoring Setup

Create health check monitors in your monitoring system:

// Example: Datadog health check
const checkHealth = async () => {
  try {
    const response = await fetch('https://api.gtmapis.com/ready', {
      timeout: 5000
    });

    if (response.ok) {
      // Service is healthy
      sendMetric('gtmapis.health', 1, { status: 'healthy' });
    } else {
      // Service is unhealthy
      sendMetric('gtmapis.health', 0, { status: 'unhealthy' });
      sendAlert('GTMAPIs readiness check failed');
    }
  } catch (error) {
    // Service is down
    sendMetric('gtmapis.health', 0, { status: 'down' });
    sendAlert('GTMAPIs is unreachable');
  }
};

// Check every 60 seconds
setInterval(checkHealth, 60000);

Load Balancer Configuration

Use /ready for load balancer health checks:

# Nginx upstream health check
upstream gtmapis {
    server api1.gtmapis.com:8080;
    server api2.gtmapis.com:8080;

    check interval=5000 rise=2 fall=3 timeout=3000 type=http;
    check_http_send "GET /ready HTTP/1.0\r\n\r\n";
    check_http_expect_alive http_2xx;
}

Deployment Strategy

Use readiness checks for zero-downtime deployments:

# Kubernetes Deployment with proper health checks
apiVersion: apps/v1
kind: Deployment
metadata:
  name: gtmapis
spec:
  replicas: 3
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 0  # Ensure zero downtime
      maxSurge: 1
  template:
    spec:
      containers:
      - name: api
        image: gtmapis:latest
        ports:
        - containerPort: 8080
        readinessProbe:
          httpGet:
            path: /ready
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 5
        livenessProbe:
          httpGet:
            path: /live
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 30

Troubleshooting

Redis Connection Failed

If /ready returns Redis error:

Cause: Redis is unreachable or down

Solution:

1. Check Redis service status
2. Verify network connectivity
3. Check Redis credentials
4. Review firewall rules

Impact: API will work but with degraded performance (no DNS caching)

DNS Resolution Failed

If /ready returns DNS error:

Cause: DNS server unreachable or misconfigured

Solution:

1. Check DNS server configuration
2. Verify network DNS settings
3. Test DNS resolution manually: dig @8.8.8.8 google.com

Impact: Email validation will fail at DNS layer

SMTP Connection Failed

If /ready returns SMTP error:

Cause: SMTP port blocked or firewall restriction

Solution:

1. Check outbound port 25 is open
2. Verify firewall rules allow SMTP
3. Test SMTP connectivity: telnet smtp.gmail.com 25

Impact: Email validation will fail at SMTP layer

Next Steps

API Overview

Explore all API endpoints

Error Handling Guide

Learn how to handle errors