REST API Documentatie

Introductie

De DSE WEBnet REST API biedt programmatische toegang tot machine-events, draaiuren, service-status en vlootstatistieken. Alle responses worden geretourneerd in JSON-formaat.

Base URL: https://<jouw-domein>/dse/api.php

Alle endpoints gebruiken de GET methode en vereisen een geldige API key.

Authenticatie

Elke request moet geauthenticeerd worden met een API key. De key kan op twee manieren meegegeven worden:

  1. HTTP Header (aanbevolen):
    X-API-Key: jouw-api-key-hier
  2. GET Parameter:
    ?api_key=jouw-api-key-hier
Endpoints
  • machines — Lijst van alle machines met laatste meting
  • events — Events voor een specifieke machine
  • stats — Vloot statistieken
  • service — Service status per machine
  • warnings — Recente warnings en criticals

GET api.php?endpoint=machines

Retourneert een lijst van alle unieke machines met hun laatste meting, draaiuren en service-uren.

Parameters
ParameterTypeVerplichtOmschrijving
endpointstringJaMoet machines zijn
Voorbeeld Response
{
    "ok": true,
    "data": [
        {
            "machine": "GEN-001",
            "last_hours": 20647,
            "service_hours": 21000,
            "last_event": "Engine Running",
            "last_time": "2026-03-07 14:30:00"
        },
        {
            "machine": "GEN-002",
            "last_hours": 8450,
            "service_hours": 10000,
            "last_event": "Engine Stopped",
            "last_time": "2026-03-07 12:15:00"
        }
    ]
}

GET api.php?endpoint=events&machine=X

Retourneert events (logboek) voor een specifieke machine, gesorteerd op tijd (nieuwste eerst). Ondersteunt paginering.

Parameters
ParameterTypeVerplichtStandaardOmschrijving
endpointstringJa—Moet events zijn
machinestringJa—Machinenaam (exact match)
limitintegerNee50Aantal resultaten (1–1000)
offsetintegerNee0Offset voor paginering
Voorbeeld Response
{
    "ok": true,
    "data": [
        {
            "id": 4521,
            "machine": "GEN-001",
            "gebeurtenis": "Engine Running",
            "tijd": "2026-03-07 14:30:00",
            "hours": "20647:28:22",
            "usbid": "USB001"
        },
        {
            "id": 4520,
            "machine": "GEN-001",
            "gebeurtenis": "Engine Stopped",
            "tijd": "2026-03-07 12:00:00",
            "hours": "20647:25:10",
            "usbid": "USB001"
        }
    ],
    "total": 123
}

GET api.php?endpoint=stats&period=30d

Retourneert samengevatte statistieken voor de gehele vloot over een gekozen periode.

Parameters
ParameterTypeVerplichtStandaardOmschrijving
endpointstringJa—Moet stats zijn
periodstringNee30dPeriode: 24h, 7d, 30d, all
Voorbeeld Response
{
    "ok": true,
    "data": {
        "total_machines": 10,
        "total_events": 500,
        "warnings": 20,
        "starts": 100,
        "stops": 95
    }
}

GET api.php?endpoint=service

Retourneert de service-status voor elke machine: huidige draaiuren, service-interval en resterende uren tot de volgende beurt.

Parameters
ParameterTypeVerplichtOmschrijving
endpointstringJaMoet service zijn
Voorbeeld Response
{
    "ok": true,
    "data": [
        {
            "machine": "GEN-001",
            "current_hours": 20647,
            "service_hours": 21000,
            "remaining": 353
        },
        {
            "machine": "GEN-002",
            "current_hours": 8450,
            "service_hours": 10000,
            "remaining": 1550
        },
        {
            "machine": "GEN-003",
            "current_hours": 5000,
            "service_hours": 0,
            "remaining": null
        }
    ]
}

remaining is null wanneer er geen service-uren zijn ingesteld (service_hours = 0). Een negatieve waarde betekent dat de machine over de servicebeurt heen is.

GET api.php?endpoint=warnings&period=7d

Retourneert alle recente events die als warning of critical worden beschouwd (o.a. Warning, Trip, Fault, Shutdown, Over Current, Electrical Trip, ELR, ITR).

Parameters
ParameterTypeVerplichtStandaardOmschrijving
endpointstringJa—Moet warnings zijn
periodstringNee7dPeriode: 24h, 7d, 30d, all
Voorbeeld Response
{
    "ok": true,
    "data": [
        {
            "id": 4510,
            "machine": "GEN-003",
            "gebeurtenis": "Warning: High Coolant Temp",
            "tijd": "2026-03-06 18:45:00",
            "hours": "5000:12:05"
        },
        {
            "id": 4498,
            "machine": "GEN-001",
            "gebeurtenis": "Electrical Trip",
            "tijd": "2026-03-05 09:12:33",
            "hours": "20640:05:11"
        }
    ]
}
Foutafhandeling

Bij fouten retourneert de API een JSON-object met "ok": false en een foutmelding.

HTTP StatusBetekenisVoorbeeld
401 Ongeldige of ontbrekende API key {"ok": false, "error": "Invalid or missing API key"}
400 Onbekend endpoint of ontbrekende parameter {"ok": false, "error": "Unknown endpoint"}
500 Interne serverfout {"ok": false, "error": "Internal server error"}
Voorbeelden
cURL (met header)
curl -H "X-API-Key: jouw-api-key" \
     "https://jouw-domein.nl/dse/api.php?endpoint=machines"
cURL (met GET parameter)
curl "https://jouw-domein.nl/dse/api.php?endpoint=events&machine=GEN-001&limit=10&api_key=jouw-api-key"
JavaScript (fetch)
const response = await fetch('api.php?endpoint=stats&period=7d', {
    headers: { 'X-API-Key': 'jouw-api-key' }
});
const data = await response.json();
console.log(data);
PHP
$ch = curl_init('https://jouw-domein.nl/dse/api.php?endpoint=service');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: jouw-api-key']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
Rate Limiting

De API hanteert rate limiting per API key. Standaard zijn maximaal 60 requests per 60 seconden toegestaan. Bij overschrijding wordt de key tijdelijk geblokkeerd en ontvang je een 429 Too Many Requests response.

Response headers

Elke response bevat de volgende rate limit headers:

HeaderBeschrijving
X-RateLimit-LimitMax. aantal requests per window
X-RateLimit-RemainingResterend aantal requests in huidig window
X-RateLimit-ResetUnix timestamp wanneer het window reset
Retry-AfterSeconden wachten (alleen bij 429)
429 Response voorbeeld
{
    "ok": false,
    "error": "Rate limit exceeded",
    "retry_after": 60
}
Configuratie

De limieten zijn instelbaar via .env: API_RATE_LIMIT (requests per window, standaard 60) en API_RATE_WINDOW (window in seconden, standaard 60).