Skip to content

Health API

The Health API provides endpoints for checking the status of the Sabdasakha service.

Endpoints

Method Endpoint Description
GET /api/v1/health Detailed health status
GET /up Simple uptime check

Health Check

Get detailed health status including database connectivity and cache statistics.

Request

GET /api/v1/health

Example Request

curl "https://sabdasakha.com/api/v1/health"

import requests

response = requests.get("https://sabdasakha.com/api/v1/health")
health = response.json()

if health["status"] == "healthy":
    print("Service is up!")

const response = await fetch("https://sabdasakha.com/api/v1/health");
const health = await response.json();

if (health.status === "healthy") {
  console.log("Service is up!");
}

Success Response (200)

{
  "status": "healthy",
  "version": "1.0.0",
  "database": {
    "connected": true,
    "entries_count": "...",
    "words_count": "..."
  },
  "cache": {
    "bloom_filter": true,
    "lru_cache_hits": 1250,
    "lru_cache_misses": 180
  }
}
Field Type Description
status string Overall health: "healthy" or "degraded"
version string API version
database.connected boolean Database connectivity
database.entries_count integer Dictionary entries available
database.words_count integer Vocabulary words for spellcheck
cache.bloom_filter boolean Bloom filter initialized
cache.lru_cache_hits integer Cache hit count
cache.lru_cache_misses integer Cache miss count

Degraded Response (200)

When some services are impaired but core functionality works:

{
  "status": "degraded",
  "version": "1.0.0",
  "database": {
    "connected": true,
    "entries_count": "...",
    "words_count": "..."
  },
  "cache": {
    "bloom_filter": false,
    "lru_cache_hits": 0,
    "lru_cache_misses": 0
  },
  "issues": ["Bloom filter not initialized - spellcheck may be slower"]
}

Simple Uptime Check

A minimal endpoint for load balancers and monitoring tools.

Request

GET /up

Example Request

curl "https://sabdasakha.com/up"

Success Response (200)

{
  "status": "ok"
}

Error Response (503)

If the service is down:

{
  "status": "error"
}

Monitoring Integration

Uptime Monitoring

Use the /up endpoint for basic uptime checks:

# Simple bash check
if curl -s https://sabdasakha.com/up | grep -q '"status":"ok"'; then
  echo "Service is up"
else
  echo "Service is down"
  # Send alert
fi

Prometheus-style Metrics

For more detailed monitoring, use the /api/v1/health endpoint:

import requests
import time

def collect_metrics():
    response = requests.get("https://sabdasakha.com/api/v1/health")
    health = response.json()

    metrics = {
        "sabdasakha_up": 1 if health["status"] == "healthy" else 0,
        "sabdasakha_db_connected": 1 if health["database"]["connected"] else 0,
        "sabdasakha_cache_hits": health["cache"]["lru_cache_hits"],
        "sabdasakha_cache_misses": health["cache"]["lru_cache_misses"],
    }

    return metrics

Health Check in Your App

Check service health before making API calls:

class SabdasakhaClient:
    def __init__(self):
        self.base_url = "https://sabdasakha.com"
        self._check_health()

    def _check_health(self):
        response = requests.get(f"{self.base_url}/up", timeout=5)
        if response.json().get("status") != "ok":
            raise ConnectionError("Sabdasakha API is unavailable")

    def lookup_word(self, word):
        # ... make API call
        pass

Status Page

For real-time service status, visit: