Skip to content

Health API Endpoints

The Health API provides comprehensive system monitoring and diagnostics for the tracker pipeline system. These endpoints are designed for consumption by the admin panel and monitoring systems.

Authentication

All health endpoints require admin authentication. You must include a valid JWT token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Endpoints

GET /api/v1/health/basic

Quick health check of core infrastructure components.

Response:

  • Database connectivity status
  • Redis connectivity status
  • Overall system status
  • Response time metrics

Example:

curl -X GET "http://localhost:8100/api/v1/health/basic" \
  -H "Authorization: Bearer <token>"

Response:

{
  "status": "healthy",
  "timestamp": "2025-07-12T12:00:00+00:00",
  "components": {
    "database": {
      "status": "healthy",
      "error": null
    },
    "redis": {
      "status": "healthy",
      "error": null
    }
  },
  "response_time_ms": 45.2
}

GET /api/v1/health/pipeline

Comprehensive tracker pipeline health status with detailed diagnostics.

Response:

  • Detailed test results for each pipeline component
  • Success rate and overall status
  • Actionable recommendations for any issues found
  • Performance metrics

Example:

curl -X GET "http://localhost:8100/api/v1/health/pipeline" \
  -H "Authorization: Bearer <token>"

Response:

{
  "status": "healthy",
  "timestamp": "2025-07-12T12:00:00+00:00",
  "success_rate": 100.0,
  "successful_steps": 4,
  "total_steps": 4,
  "test_steps": {
    "check_views_and_policies": {
      "name": "Check Views and Policies",
      "success": true,
      "details": {
        "views_status": {
          "location_history_hourly": true,
          "location_history_daily": true,
          "location_history": true
        }
      },
      "issues": []
    }
  },
  "recommendations": [
    {
      "severity": "info",
      "issue": "All tests passed",
      "action": "System is healthy - continue monitoring",
      "documentation": "Health monitoring documentation"
    }
  ],
  "response_time_ms": 1250.5
}

GET /api/v1/health/system

Overall system health combining basic and pipeline checks.

Response:

  • Combined health status (healthy, degraded, unhealthy, critical)
  • Basic infrastructure health details
  • Complete pipeline health analysis
  • Overall system metrics

Example:

curl -X GET "http://localhost:8100/api/v1/health/system" \
  -H "Authorization: Bearer <token>"

GET /api/v1/health/status

Simple health status for quick checks.

Response:

  • Simple status string
  • Timestamp of the check

Example:

curl -X GET "http://localhost:8100/api/v1/health/status" \
  -H "Authorization: Bearer <token>"

Response:

{
  "status": "healthy",
  "timestamp": "2025-07-12T12:00:00+00:00"
}

Status Values

Basic Health Status

  • healthy: All components are functioning normally
  • unhealthy: One or more components have issues

Pipeline Health Status

  • healthy: All pipeline tests passed (≥80% success rate)
  • degraded: Some issues but system is functional (60-79% success rate)
  • unhealthy: Significant issues detected (<60% success rate)
  • error: Health check system failure

System Health Status

  • healthy: Both basic and pipeline health are good
  • degraded: Basic health is good but pipeline has issues
  • unhealthy: Pipeline has significant issues
  • critical: Basic infrastructure is failing

Integration with Admin Panel

The admin panel can use these endpoints to:

  1. Dashboard Widget: Use /health/status for a simple status indicator
  2. Detailed View: Use /health/system for comprehensive health information
  3. Diagnostics Page: Use /health/pipeline for detailed troubleshooting
  4. Infrastructure Monitoring: Use /health/basic for core system checks

Performance Considerations

  • /health/basic: Fast (~50ms) - suitable for frequent polling
  • /health/status: Fast (~50ms) - lightweight status check
  • /health/pipeline: Slower (~1-3s) - comprehensive testing, use sparingly
  • /health/system: Slower (~1-3s) - combines all checks

Error Handling

All endpoints return appropriate HTTP status codes:

  • 200 OK: Health check completed successfully
  • 401 Unauthorized: Missing or invalid authentication token
  • 403 Forbidden: User does not have admin privileges
  • 500 Internal Server Error: Health check system failure

Error responses include detailed error messages:

{
  "detail": "Health check failed: Database connection timeout"
}

Monitoring Integration

These endpoints can be integrated with monitoring systems:

  • Prometheus: Scrape /health/status for metrics
  • Grafana: Create dashboards using the JSON responses
  • Alerting: Set up alerts based on status changes
  • Load Balancers: Use /health/basic for health checks

Testing

The Health API has comprehensive behavioral test coverage that validates real-world admin panel workflows:

Test Coverage

  • 41 comprehensive tests covering all major business scenarios
  • API Integration Tests: Dashboard integration, authentication, error handling
  • Service Operation Tests: Health checks, diagnostics, system monitoring
  • End-to-End Workflow Tests: Complete admin workflows from health assessment to incident response
  • Performance Validation: Response time requirements for dashboard widgets
  • Schema Compliance: 100% Pydantic model validation

Test Organization

tests/behaviors/health_monitoring/
├── test_health_api_routes.py          # API endpoint behavioral tests (17 tests)
├── test_health_service_operations.py  # Service layer behavioral tests (20 tests)
└── test_health_integration_workflows.py # End-to-end workflow tests (4 tests)

Running Health API Tests

# Run all health monitoring tests
./run_tests_with_coverage.sh tests/behaviors/health_monitoring/

# Run specific test categories
./run_tests_with_coverage.sh tests/behaviors/health_monitoring/test_health_api_routes.py
./run_tests_with_coverage.sh tests/behaviors/health_monitoring/test_health_service_operations.py
./run_tests_with_coverage.sh tests/behaviors/health_monitoring/test_health_integration_workflows.py

Test Scenarios Covered

  • Admin Panel Integration: Dashboard loading, status widgets, real-time updates
  • Authentication & Authorization: Admin-only access, token validation, error handling
  • Performance Requirements: Response time validation for different endpoint types
  • Error Recovery: Database failures, partial service failures, graceful degradation
  • Business Workflows: Daily health assessments, incident response, troubleshooting
  • Compliance & Reporting: Management reporting, audit trails, business continuity

For detailed testing implementation information, see Health API Testing Implementation.