API Healthcheck Endpoint

A healthcheck endpoint (or health check) is a dedicated entry point of your API that allows you to quickly verify if the service is operational. Unlike functional endpoints that process business data, the healthcheck has a single objective: answer "yes, I'm working" or "no, there's a problem". It's the foundation of any effective API monitoring system.

Designing a good healthcheck is more subtle than it seems. A healthcheck that's too simple (always returns 200) doesn't detect anything useful. A healthcheck that's too complex (tests everything) becomes slow and can itself fail. The art is finding the right balance: check critical dependencies without creating an additional point of fragility.

MoniTao uses your healthcheck endpoints to continuously monitor your API health. By properly configuring your healthcheck and connecting it to MoniTao, you get real-time visibility into your services availability and immediate alerts when problems occur.

Why a Healthcheck Endpoint is Essential

A well-designed healthcheck brings benefits at multiple levels of your infrastructure:

• External monitoring: allows tools like MoniTao to verify your API is accessible and functional from outside your network.
• Load balancer: load balancers use healthcheck to decide if an instance can receive traffic. A failing instance is automatically excluded.
• Orchestration: Kubernetes, Docker Swarm and other orchestrators use liveness/readiness probes based on healthcheck to restart or replace containers.
• Quick diagnosis: during an incident, healthcheck gives a quick first indication: is the service responding? Are its dependencies accessible?

Types of Healthcheck

Depending on the level of verification desired, several approaches are possible:

• Simple healthcheck (ping): returns 200 OK if HTTP server responds. Doesn't check anything else. Useful to confirm the process is alive.
• Application healthcheck (shallow): verifies the application starts correctly and can process requests. Usually includes a memory or routing test.
• Dependencies healthcheck (deep): tests connections to critical dependencies: database, cache, external services. More comprehensive but slower.
• Detailed healthcheck: returns a detailed status of each component (JSON). Allows precise diagnosis of which element is failing.

How to Implement a Healthcheck

Follow these steps to create an effective healthcheck endpoint:

1. Choose the URL: use a standard convention like /health, /healthz, /status, or /api/health. Avoid URLs that are too long or obscure.
2. Define the checks: identify critical dependencies without which your API cannot function: database, required cache, etc.
3. Implement the tests: for each dependency, create a quick test (ping, connection) with short timeout (1-2 seconds max).
4. Return a clear status: HTTP 200 if all is well, HTTP 503 if a critical dependency is down. Include a JSON body with details.

Healthcheck Implementation Example

Here's a complete healthcheck endpoint example in PHP:

<?php
// /api/health.php - Healthcheck Endpoint

header('Content-Type: application/json');

$checks = [
    'status' => 'healthy',
    'timestamp' => date('c'),
    'checks' => []
];

$allHealthy = true;

// Test database connection
try {
    $pdo = new PDO($dsn, $user, $pass, [PDO::ATTR_TIMEOUT => 2]);
    $pdo->query('SELECT 1');
    $checks['checks']['database'] = ['status' => 'ok'];
} catch (Exception $e) {
    $checks['checks']['database'] = ['status' => 'error', 'message' => 'Connection failed'];
    $allHealthy = false;
}

// Test Redis connection (optional)
try {
    $redis = new Redis();
    $redis->connect('127.0.0.1', 6379, 1);
    $redis->ping();
    $checks['checks']['redis'] = ['status' => 'ok'];
} catch (Exception $e) {
    $checks['checks']['redis'] = ['status' => 'warning', 'message' => 'Cache unavailable'];
}

// Final status
if (!$allHealthy) {
    http_response_code(503);
    $checks['status'] = 'unhealthy';
}

echo json_encode($checks);

This example checks the database (critical) and Redis (optional). If database is inaccessible, healthcheck returns 503. Redis down returns a warning but not a total failure.

Healthcheck Best Practices

Adopt these practices for a reliable and effective healthcheck:

• Short timeout: each check should have a 1-2 second max timeout. A slow healthcheck is a problem in itself.
• Avoid authentication: healthcheck should be accessible without auth to simplify external monitoring and load balancers.
• Don't modify anything: healthcheck must be a read-only operation. No database writes, no side effects.
• Distinguish critical from optional: a cache being down shouldn't fail healthcheck if API can work (slowly) without it.

Frequently Asked Questions - API Healthcheck

A Well-Designed Healthcheck Changes Everything

A healthcheck endpoint is not a luxury, it's a necessity for any professional API. It allows load balancers to route traffic correctly, orchestrators to keep your services alive, and monitoring tools to detect problems before your users.

With MoniTao, connect your healthcheck in seconds and benefit from continuous monitoring. You'll be alerted as soon as a critical dependency becomes inaccessible, well before your users notice the problem.

Ready to Sleep Soundly?

Start free, no credit card required.

Create My Account See pricing