Skip to main content

​
Overview

The Meta-Data Tag Generator API provides two endpoints for monitoring service health and availability. These endpoints are essential for deployment verification, uptime monitoring, and ensuring the API is operational.

​
GET /api/health

Comprehensive health check endpoint that returns detailed service status, version information, and a confirmation message.

​
Use Cases

  • Deployment Verification: Confirm successful deployment after updates
  • Monitoring Systems: Integrate with health check monitoring tools (Datadog, New Relic, etc.)
  • Load Balancer Health Checks: Configure load balancers to verify backend availability
  • Frontend Status Checks: Verify API connectivity before making requests

​
Request

curl https://your-api-domain.com/api/health

​
Response

​
status
string
required
Current health status of the API. Returns "healthy" when operational.
​
version
string
required
Current API version. Example: "1.0.0"
​
message
string
required
Human-readable confirmation message. Returns "Document Meta-Tagging API is running"

​
Response Example

{
  "status": "healthy",
  "version": "1.0.0",
  "message": "Document Meta-Tagging API is running"
}

​
Response Codes

​
200
Success
API is running and healthy
​
500
Error
Service error (endpoint should always return 200 if reachable)

​
GET /api/status

Simple status check endpoint for quick API availability verification. Returns minimal response for basic health checks.

​
Use Cases

  • Quick Health Checks: Lightweight ping to verify API is responding
  • Simple Monitoring: Basic uptime monitoring without detailed information
  • Container Health Checks: Docker/Kubernetes liveness probes
  • API Gateway Health: Lightweight checks for API gateway routing

​
Request

curl https://your-api-domain.com/api/status

​
Response

​
status
string
required
Simple status indicator. Returns "ok" when operational.
​
service
string
required
Service identifier. Returns "document-meta-tagging-api"

​
Response Example

{
  "status": "ok",
  "service": "document-meta-tagging-api"
}

​
Response Codes

​
200
Success
API is responding normally
​
500
Error
Service error (endpoint should always return 200 if reachable)

​
Health vs Status

Feature/api/health/api/status
Response SizeDetailedMinimal
Version InfoYesNo
MessageDescriptiveNone
Use CaseComprehensive monitoringQuick availability check
Recommended ForProduction monitoring, deployment verificationContainer health probes, lightweight checks

​
Frontend Integration

The health endpoint is used in the frontend API client: 
// frontend/lib/api.ts
export async function checkHealth(): Promise<HealthCheckResponse> {
  const response = await fetch(`${API_BASE_URL}/health`);
  return response.json();
}
Usage in Components: 
import { checkHealth } from '@/lib/api';

// Verify API connectivity
const health = await checkHealth();
console.log(`API Status: ${health.status} (v${health.version})`);

​
Monitoring Best Practices

​
1. Configure Health Check Intervals

# Example: Docker Compose health check
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8000/api/health"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 40s

​
2. Set Up Uptime Monitoring

Monitor the /api/health endpoint with services like:
  • Uptime Robot: Free tier supports 50 monitors
  • Pingdom: Advanced monitoring with alerting
  • Datadog: Full observability and APM
  • New Relic: Application performance monitoring

​
3. Load Balancer Configuration

# Example: Nginx upstream health check
upstream api_backend {
  server api1.example.com:8000;
  server api2.example.com:8000;
  
  # Health check configuration
  health_check interval=10s
               fails=3
               passes=2
               uri=/api/health
               match=health_ok;
}

match health_ok {
  status 200;
  body ~ "healthy";
}

​
4. Kubernetes Liveness Probe

# Example: Kubernetes deployment
livenessProbe:
  httpGet:
    path: /api/status
    port: 8000
  initialDelaySeconds: 30
  periodSeconds: 10
  timeoutSeconds: 5
  failureThreshold: 3

readinessProbe:
  httpGet:
    path: /api/health
    port: 8000
  initialDelaySeconds: 10
  periodSeconds: 5
  timeoutSeconds: 3

​
Troubleshooting

​
Health Check Fails

If health checks are failing:
  1. Verify API is Running 
    curl http://localhost:8000/api/status
  2. Check Service Logs 
    docker logs <container-name>
  3. Test Network Connectivity 
    nc -zv localhost 8000
  4. Verify Port Binding 
    netstat -tulpn | grep 8000

​
Intermittent Health Check Failures

Common causes:
  • High CPU/Memory Usage: Service is overwhelmed
  • Network Latency: Timeout too aggressive
  • Cold Start: Container/service still initializing
  • Rate Limiting: Too many health check requests
Solution: Adjust health check intervals and timeouts based on your service’s performance characteristics.

Build docs developers (and LLMs) love

Get started for freeTalk to us