Health API - Document Converter API

Overview

The Health API provides endpoints to check the application’s health status and readiness, essential for monitoring and load balancing in production environments.

Health Check

Response

status

string

required

Health status of the applicationValues: healthy, unhealthy

timestamp

string

required

Current timestamp in ISO 8601 format

version

string

required

Application version

uptime

number

Application uptime in seconds

curl "http://localhost:8000/api/v1/health"

Response Example

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "1.0.0",
  "uptime": 3600
}

This endpoint always returns 200 OK if the application is running. Use the readiness endpoint for dependency checks.

Readiness Check

Response

status

string

required

Readiness status of the applicationValues: ready, not ready

timestamp

string

required

Current timestamp in ISO 8601 format

services

object

required

Status of individual service dependencies

services.redis

boolean

required

Redis connection status

services.celery

boolean

required

Celery worker availability

services.storage

boolean

File storage system status

services.ocr

object

OCR providers availability

curl "http://localhost:8000/api/v1/ready"

Response Examples

Ready
Not Ready

{
  "status": "ready",
  "timestamp": "2024-01-15T10:30:00Z",
  "services": {
    "redis": true,
    "celery": true,
    "storage": true,
    "ocr": {
      "paddle": true,
      "easyocr": true,
      "mistral": false
    }
  }
}

HTTP Status: 200 OK

{
  "status": "not ready",
  "timestamp": "2024-01-15T10:30:00Z",
  "services": {
    "redis": false,
    "celery": false,
    "storage": true,
    "ocr": {
      "paddle": true,
      "easyocr": false,
      "mistral": false
    }
  }
}

HTTP Status: 503 Service Unavailable

Service Dependencies

Redis

Purpose: Task queue and job storageCheck: Connection test with PING commandCommon Issues:

Redis server not running
Connection refused
Authentication failure
Network connectivity issues

Troubleshooting:

# Test Redis connection
redis-cli -u $REDIS_URL ping

# Check Redis status
redis-cli info server

Celery

Purpose: Background task processingCheck: Worker availability and task queue connectivityCommon Issues:

No workers running
Worker process crashed
Task routing problems
Memory issues

Troubleshooting:

# Check active workers
celery -A src.services.celery_app inspect active

# Check worker stats
celery -A src.services.celery_app inspect stats

Storage

Purpose: File upload and result storageCheck: Directory accessibility and disk spaceCommon Issues:

Directory permissions
Disk full
Mount point issues
File system errors

Troubleshooting:

# Check disk space
df -h

# Check directory permissions
ls -la /path/to/upload/dir

OCR Providers

Purpose: Text extraction from imagesCheck: Provider initialization and model availabilityCommon Issues:

Missing models
GPU unavailable
API key invalid
Library compatibility

Troubleshooting:

# Test OCR provider
python -c "from src.services.ocr_service import ocr_service; print(ocr_service.get_available_providers())"

Load Balancer Configuration

Nginx
HAProxy
Kubernetes

upstream doc_converter {
    server 127.0.0.1:8000;
    server 127.0.0.1:8001;
    server 127.0.0.1:8002;
}

server {
    listen 80;
    server_name api.example.com;

    # Health check endpoint
    location /health {
        access_log off;
        proxy_pass http://doc_converter/api/v1/health;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # Readiness check for load balancer
    location /ready {
        access_log off;
        proxy_pass http://doc_converter/api/v1/ready;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # Main application
    location / {
        proxy_pass http://doc_converter;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

backend doc_converter
    balance roundrobin
    option httpchk GET /api/v1/ready
    http-check expect status 200
    server app1 127.0.0.1:8000 check
    server app2 127.0.0.1:8001 check
    server app3 127.0.0.1:8002 check

frontend doc_converter_frontend
    bind *:80
    default_backend doc_converter
    
    # Health check bypass
    acl health_check path_beg /api/v1/health
    acl ready_check path_beg /api/v1/ready
    
    use_backend doc_converter if health_check
    use_backend doc_converter if ready_check

apiVersion: apps/v1
kind: Deployment
metadata:
  name: doc-converter
spec:
  replicas: 3
  selector:
    matchLabels:
      app: doc-converter
  template:
    metadata:
      labels:
        app: doc-converter
    spec:
      containers:
      - name: doc-converter
        image: doc-converter:latest
        ports:
        - containerPort: 8000
        livenessProbe:
          httpGet:
            path: /api/v1/health
            port: 8000
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /api/v1/ready
            port: 8000
          initialDelaySeconds: 5
          periodSeconds: 5
        resources:
          requests:
            memory: "512Mi"
            cpu: "250m"
          limits:
            memory: "1Gi"
            cpu: "500m"

Monitoring Integration

from prometheus_client import Counter, Histogram, Gauge
import time

# Define metrics
health_check_counter = Counter('health_checks_total', 'Total health checks')
readiness_check_counter = Counter('readiness_checks_total', 'Total readiness checks')
response_time_histogram = Histogram('health_check_duration_seconds', 'Health check response time')

@app.get("/api/v1/health")
async def health_check():
    start_time = time.time()
    
    try:
        health_check_counter.inc()
        
        # Your health check logic here
        result = {
            "status": "healthy",
            "timestamp": datetime.utcnow().isoformat() + "Z",
            "version": "1.0.0"
        }
        
        return result
    
    finally:
        response_time_histogram.observe(time.time() - start_time)

Best Practices

Fast Response

Health and readiness checks should respond quickly (< 1 second) to avoid load balancer timeouts.

Dependency Checks

Readiness checks should validate all critical dependencies but avoid expensive operations.

Graceful Degradation

Consider partial readiness states where some non-critical services may be unavailable.

Monitoring Integration

Integrate health checks with monitoring systems for proactive alerting.

Troubleshooting

Health Check Fails

Symptoms: Health endpoint returns 5xx error or doesn’t respondCauses:

Application crashed
Port not accessible
Network issues
Configuration problems

Solutions:

Check application logs
Verify port binding
Test network connectivity
Restart the application

Readiness Check Fails

Symptoms: Readiness endpoint returns “not ready” statusCauses:

Redis connection issues
Celery workers not running
Storage system problems
OCR providers not initialized

Solutions:

Check individual service status
Restart failed services
Verify configuration
Check resource availability

Intermittent Failures

Symptoms: Health checks pass sometimes, fail other timesCauses:

Resource exhaustion
Network instability
Database connection pooling issues
Memory leaks

Solutions:

Monitor resource usage
Increase timeout values
Implement retry logic
Scale resources appropriately

Next Steps

Error Handling

Learn about API error responses and codes

Production Deployment

Deploy with proper health monitoring

Monitoring

Set up comprehensive monitoring

Jobs API

Learn about the main Jobs API

Documentation Index

​Overview

​Health Check

​Response

​Response Example

​Readiness Check

​Response

​Response Examples

​Service Dependencies

​Load Balancer Configuration

​Monitoring Integration

​Best Practices

Fast Response

Dependency Checks

Graceful Degradation

Monitoring Integration

​Troubleshooting

​Next Steps

Error Handling

Production Deployment

Monitoring

Jobs API

Overview

Health Check

Response

Response Example

Readiness Check

Response

Response Examples

Service Dependencies

Load Balancer Configuration

Monitoring Integration

Best Practices

Troubleshooting

Next Steps