Health Check

Monitor the status and availability of the Sakneen API using the health check endpoint.

Health Check Endpoint

The health check endpoint allows you to verify that the API is running and accessible.

Endpoint Details

• Method: GET
• Path: /external/apis/v1.0/healthz
• Authentication: Not required (publicly accessible)

info

The health check endpoint does not require an API key. This allows external monitoring tools and load balancers to verify API availability without credentials.

Request Example

curl --location 'https://your-domain/external/apis/v1.0/healthz'

Local Development:

curl --location 'http://localhost:8080/external/apis/v1.0/healthz'

Response

A successful health check returns an HTTP 200 status code with a JSON body indicating the API is healthy and operational.

Success Response (200 OK):

{
  "description": "Backend APIs for the Sakneen platform",
  "ok": true,
  "version": "v1.0"
}

Integration Examples

JavaScript/Node.js

const checkApiHealth = async () => {
  const domain = process.env.SAKNEEN_DOMAIN; // your assigned domain
  
  try {
    const response = await fetch(`https://${domain}/external/apis/v1.0/healthz`, {
      method: 'GET',
    });
    
    if (response.ok) {
      const data = await response.json();
      console.log('API Health Status:', data);
      return data.ok === true;
    } else {
      console.error('API Health Check Failed:', response.status);
      return false;
    }
  } catch (error) {
    console.error('Health check error:', error);
    return false;
  }
};

// Usage
checkApiHealth().then(isHealthy => {
  if (isHealthy) {
    console.log('API is ready for use');
  } else {
    console.log('API is not available');
  }
});

Python

import requests
import os

def check_api_health():
    domain = os.getenv('SAKNEEN_DOMAIN')  # your assigned domain
    
    try:
        response = requests.get(
            f'https://{domain}/external/apis/v1.0/healthz'
        )
        
        if response.status_code == 200:
            data = response.json()
            print(f'API Health Status: {data}')
            return data.get('ok') is True
        else:
            print(f'API Health Check Failed: {response.status_code}')
            return False
            
    except requests.exceptions.RequestException as e:
        print(f'Health check error: {e}')
        return False

# Usage
if check_api_health():
    print('API is ready for use')
else:
    print('API is not available')

PHP

<?php
function checkApiHealth() {
    $domain = $_ENV['SAKNEEN_DOMAIN']; // your assigned domain
    
    $curl = curl_init();
    curl_setopt_array($curl, [
        CURLOPT_URL => "https://{$domain}/external/apis/v1.0/healthz",
        CURLOPT_RETURNTRANSFER => true,
    ]);
    
    $response = curl_exec($curl);
    $httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
    curl_close($curl);
    
    if ($httpCode === 200) {
        $data = json_decode($response, true);
        echo "API Health Status: " . json_encode($data) . "\n";
        return $data['ok'] === true;
    } else {
        echo "API Health Check Failed: $httpCode\n";
        return false;
    }
}

// Usage
if (checkApiHealth()) {
    echo "API is ready for use\n";
} else {
    echo "API is not available\n";
}
?>

Monitoring and Alerting

Automated Health Checks

You can set up automated health checks to monitor your API availability:

// Health check every 5 minutes
setInterval(async () => {
  const isHealthy = await checkApiHealth();
  
  if (!isHealthy) {
    // Send alert to your monitoring system
    console.error('ALERT: Sakneen API is not responding');
    // You could send notifications, emails, etc.
  }
}, 5 * 60 * 1000); // 5 minutes

Load Balancer Health Checks

If you're using a load balancer, configure it to use this endpoint for health checks. Since no authentication is required, you can use it directly:

# Example for AWS Application Load Balancer
healthcheck:
  path: /external/apis/v1.0/healthz
  interval: 30
  timeout: 5
  retries: 3

Best Practices

1. Regular Monitoring: Implement regular health checks in your application
2. Error Handling: Always handle health check failures gracefully
3. Timeout Configuration: Set appropriate timeouts for health check requests
4. Logging: Log health check results for monitoring and debugging
5. Fallback Logic: Implement fallback mechanisms when health checks fail

Troubleshooting

Common Issues

Connection Timeout

• Check your network connectivity
• Verify the domain is correct
• Ensure you're using the right protocol (http vs https)

503 Service Unavailable

• The API might be temporarily down for maintenance
• Contact support if the issue persists

Unexpected Response Format

• Ensure you're parsing the response as JSON
• The response body is {"description": "...", "ok": true, "version": "v1.0"}

Contact Support

If you're experiencing persistent health check failures:

• Email: [email protected]
• Include your domain and any error messages
• Provide error messages and timestamps
• Describe your network setup if relevant