# Loadify API Documentation

> Documentation au format Markdown destinée aux assistants IA (LLM).
> Pour la version interactive HTML, voir `https://loadify.fr/docs/api/`.

Loadify est un dashboard de monitoring temps réel de la charge des serveurs dédiés DYEZ. Cette API REST expose la charge actuelle et historique des serveurs surveillés (via SSH + cron).

- **URL de base** : `https://loadify.fr`
- **Format** : JSON (`application/json`)
- **Encodage** : UTF-8
- **Méthodes** : GET uniquement (lecture seule)

## Authentification

**Aucune authentification** n'est requise. Loadify est un dashboard public en lecture seule depuis la suppression de l'interface admin (audit sécurité du 2026-04-02). Les valeurs de charge ne sont pas considérées comme sensibles.

Les variables `API_KEY` et `ENCRYPTION_KEY` du `.env` ne servent **pas** pour l'API HTTP : elles sont utilisées en interne pour chiffrer les mots de passe SSH en base (AES-256-CBC).

## Conventions

- **Méthodes** : `GET` uniquement.
- **Horodatages** : format `YYYY-MM-DD HH:MM:SS`, fuseau Europe/Paris pour `/api/status.json` et `/api/get-current.php`. Les labels de `/api/get-history.php` sont décalés `+1 HOUR` côté SQL pour s'aligner sur ce fuseau.
- **Floats** : `/api/status.json` arrondit à 2 décimales et émet des nombres natifs (pas de chaînes). Les autres endpoints renvoient les valeurs brutes en `float`.
- **CORS** : non activé. Pas d'appels cross-origin navigateur sans proxy.
- **Rate limiting** : pas de limite stricte. Les mesures sont rafraîchies une fois par minute par cron, inutile de poller plus souvent.

## Codes d'erreur

| Code | Statut                | Description                                   |
| ---- | --------------------- | --------------------------------------------- |
| 200  | OK                    | Requête traitée avec succès.                  |
| 400  | Bad Request           | Paramètre obligatoire manquant ou invalide.   |
| 404  | Not Found             | Route ou ressource inexistante.               |
| 500  | Internal Server Error | Erreur serveur (typiquement base de données). |

Les erreurs `/api/get-current.php` et `/api/get-history.php` suivent la forme `{"success": false, "error": "..."}`. L'endpoint `/api/status.json` retourne `{"error": "Service unavailable"}`.

## Public
### GET /api/status.json

Charge actuelle de tous les serveurs (endpoint public stable).

**Authentification** : Public (aucune authentification)

Retourne la dernière mesure de charge (`load_1min`, `load_5min`, `load_15min`) pour chaque serveur actif, indexée par **nom de serveur**. Les valeurs sont arrondies à 2 décimales (numériques, pas chaînes). Réécrit en interne vers `/api/status.json.php` via `.htaccess`. Pas de cache HTTP (`Cache-Control: no-cache, must-revalidate`).

**Réponse** (application/json)

```json
{
    "servers": {
        "SRV4": {
            "load_1min": 1.24,
            "load_5min": 1.18,
            "load_15min": 1.05,
            "collected_at": "2026-05-13 09:42:01"
        },
        "SRV5": {
            "load_1min": 0.87,
            "load_5min": 0.91,
            "load_15min": 0.94,
            "collected_at": "2026-05-13 09:42:01"
        }
    },
    "generated_at": "2026-05-13 09:42:14"
}
```

**Erreurs**

- `500` : Erreur base de données. La réponse vaut `{"error":"Service unavailable"}`.

**Exemple cURL**

```bash
curl "https://loadify.fr/api/status.json"
```


## Dashboard
### GET /api/get-current.php

Dernière mesure de charge par serveur, format dashboard interne.

**Authentification** : Public (aucune authentification)

Endpoint consommé par le dashboard HTML (`assets/js/dashboard.js`). Retourne un tableau ordonné (par `display_order` puis `name`) avec `id` numérique, `name`, les 3 valeurs de charge (float natif, non arrondies), `collected_at` et un `status` (`online` ou `no_data` si aucune mesure récente). Timezone Europe/Paris pour le champ `timestamp`.

**Réponse** (application/json)

```json
{
    "success": true,
    "data": [
        {
            "id": 1,
            "name": "SRV4",
            "load_1min": 1.24,
            "load_5min": 1.18,
            "load_15min": 1.05,
            "collected_at": "2026-05-13 09:42:01",
            "status": "online"
        },
        {
            "id": 2,
            "name": "SRV5",
            "load_1min": null,
            "load_5min": null,
            "load_15min": null,
            "collected_at": null,
            "status": "no_data"
        }
    ],
    "timestamp": "2026-05-13 09:42:14"
}
```

**Erreurs**

- `500` : Erreur interne. La réponse vaut `{"success":false,"error":"Internal server error"}` (les détails sont loggés via `error_log`).

**Exemple cURL**

```bash
curl "https://loadify.fr/api/get-current.php"
```

### GET /api/get-history.php

Historique de charge pour un serveur, prêt pour Chart.js.

**Authentification** : Public (aucune authentification)

Retourne la série temporelle de charge d'un serveur sur les **2 dernières heures** ou les **24 dernières heures**. La structure de la réponse correspond directement au format attendu par Chart.js (`labels`, `datasets`). Les labels sont au format `HH:MM` (Europe/Paris : la requête SQL ajoute `+1 HOUR` au timestamp UTC).

**Paramètres de requête (query string)**

| Nom       | Type    | Requis | Description                                                                                                    |
| --------- | ------- | ------ | -------------------------------------------------------------------------------------------------------------- |
| server_id | integer | oui    | Identifiant numérique du serveur (table `servers`). Renvoyé par `/api/get-current.php` dans le champ `id`.     |
| period    | string  | non    | Plage temporelle : `2h` (défaut) ou `24h`. Toute autre valeur retombe sur `2h` (whitelist anti-injection SQL). |

**Réponse** (application/json)

```json
{
    "success": true,
    "data": {
        "labels": ["08:42", "08:43", "08:44", "08:45"],
        "datasets": [
            {
                "label": "Load 1min",
                "data": [1.24, 1.31, 1.18, 1.22],
                "borderColor": "#3498db",
                "fill": true
            },
            {
                "label": "Load 5min",
                "data": [1.18, 1.20, 1.15, 1.17],
                "borderColor": "#2ecc71",
                "fill": true
            },
            {
                "label": "Load 15min",
                "data": [1.05, 1.06, 1.05, 1.06],
                "borderColor": "#e74c3c",
                "fill": true
            }
        ]
    },
    "period": "2h",
    "count": 4
}
```

**Erreurs**

- `400` : Paramètre `server_id` manquant. La réponse vaut `{"success":false,"error":"server_id is required"}`.

**Exemple cURL**

```bash
curl "https://loadify.fr/api/get-history.php?server_id=1&period=24h"
```


## Exemple d'intégration (PHP)

```php
// Récupérer la charge actuelle de tous les serveurs
$json = file_get_contents('https://loadify.fr/api/status.json');
$data = json_decode($json, true);

foreach ($data['servers'] as $name => $metrics) {
    if ($metrics['load_1min'] > 50) {
        // alerter, throttle, etc.
    }
}
```

## Exemple d'intégration (bash + jq)

```bash
# Charge 1 min du serveur SRV4
curl -s 'https://loadify.fr/api/status.json' | jq '.servers.SRV4.load_1min'

# Liste des serveurs en alerte (load_1min > 10)
curl -s 'https://loadify.fr/api/status.json' \
  | jq '.servers | to_entries[] | select(.value.load_1min > 10) | .key'
```

---

Documentation générée dynamiquement depuis le code source Loadify.
Pour signaler une incohérence ou demander un nouvel endpoint, contacter cedric@dyez.fr.