Saltar a contenido

Health Check

Verifica el estado de salud de la API e información de versión.

Endpoint

GET /api/health

Autenticación

❌ No requiere autenticación - Este es el único endpoint público que no requiere una clave de API.

Descripción

El endpoint de health proporciona información sobre el estado actual de la API, versión e información de compilación. Es útil para:

  • Monitorear la disponibilidad de la API
  • Verificar la versión desplegada
  • Verificar conectividad antes de realizar solicitudes autenticadas
  • Health checks en entornos contenerizados

Solicitud

No requiere parámetros.

Ejemplo de Solicitud

=== "cURL"

curl https://subx-api.duckdns.org/api/health

import requests

response = requests.get("https://subx-api.duckdns.org/api/health")
data = response.json()

print(f"Status: {data['status']}")
print(f"Version: {data.get('version', 'unknown')}")

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    resp, err := http.Get("https://subx-api.duckdns.org/api/health")
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)

    fmt.Printf("Status: %v\n", result["status"])
    fmt.Printf("Version: %v\n", result["version"])
}

using System;
using System.Net.Http;
using System.Text.Json;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        using var client = new HttpClient();
        var response = await client.GetAsync("https://subx-api.duckdns.org/api/health");
        var json = await response.Content.ReadAsStringAsync();
        var data = JsonSerializer.Deserialize<JsonElement>(json);

        Console.WriteLine($"Status: {data.GetProperty("status")}");
        Console.WriteLine($"Version: {data.GetProperty("version")}");
    }
}

const response = await fetch('https://subx-api.duckdns.org/api/health');
const data = await response.json();

console.log(`Status: ${data.status}`);
console.log(`Version: ${data.version}`);

Respuesta

Respuesta Exitosa (200 OK)

{
  "status": "ok",
  "version": "1.0.0",
  "built_at": "2024-01-15T10:30:00Z"
}

Campos de Respuesta

Campo Tipo Descripción
status string Siempre "ok" cuando la API está saludable
version string Número de versión de la API (versionado semántico)
built_at string Timestamp ISO 8601 de cuándo fue compilada la API

Códigos de Estado

Código Descripción
200 La API está saludable y operativa
503 La API está temporalmente no disponible (raro)

Casos de Uso

1. Monitoreo y Alertas

Usa este endpoint en tu sistema de monitoreo para verificar la disponibilidad de la API:

import requests
import time

def check_api_health():
    try:
        response = requests.get("https://subx-api.duckdns.org/api/health", timeout=5)
        if response.status_code == 200:
            data = response.json()
            if data.get("status") == "ok":
                return True, f"API healthy (version {data.get('version')})"
        return False, f"API unhealthy (status code: {response.status_code})"
    except requests.exceptions.RequestException as e:
        return False, f"API unreachable: {e}"

# Check every 60 seconds
while True:
    is_healthy, message = check_api_health()
    print(f"[{time.strftime('%Y-%m-%d %H:%M:%S')}] {message}")
    time.sleep(60)

2. Verificación de Versión

Verifica si estás usando la última versión de la API:

import requests

response = requests.get("https://subx-api.duckdns.org/api/health")
data = response.json()

current_version = data.get("version")
print(f"Current API version: {current_version}")

# Compare with expected version
EXPECTED_VERSION = "1.0.0"
if current_version != EXPECTED_VERSION:
    print(f"⚠️ Warning: API version mismatch. Expected {EXPECTED_VERSION}, got {current_version}")

3. Docker Health Check

Usa en Docker Compose o health checks de Kubernetes:

# docker-compose.yml
services:
  my-app:
    image: my-app:latest
    depends_on:
      - subx-api
    healthcheck:
      test: ["CMD", "curl", "-f", "http://subx-api:8000/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3

4. Verificación Pre-vuelo

Verifica conectividad antes de hacer solicitudes autenticadas:

import requests

def verify_api_connectivity():
    """Verify API is accessible before proceeding."""
    try:
        response = requests.get("https://subx-api.duckdns.org/api/health", timeout=5)
        return response.status_code == 200
    except:
        return False

if __name__ == "__main__":
    if not verify_api_connectivity():
        print("❌ Cannot reach SubX API. Check your internet connection.")
        exit(1)

    print("✓ API is accessible. Proceeding with requests...")
    # Your API calls here

Notas

  • Este endpoint no tiene límite de tasa - puedes llamarlo tan seguido como necesites
  • El tiempo de respuesta es típicamente < 100ms
  • No cuenta hacia tu cuota de uso de la API
  • Cacheado por CDN para mejor rendimiento

Próximos Pasos