REST-Datenquellen

REST-Quellen binden externe Systeme (Shop, CRM, ERP, Headless-CMS, eigene Services …) als Datenquelle an. Im Template verhalten sie sich wie Collections: data("produkte") ruft die API ab, extrahiert die Liste und cacht das Ergebnis.

Quellen-Objekt

{
  "id": 1,
  "slug": "produkte",
  "name": "Shop-Produkte",
  "method": "GET",
  "url": "https://shop.example.com/api/products?category={cat}&limit={limit}",
  "headers": { "Authorization": "Bearer {env.SHOP_TOKEN}" },
  "body": "",
  "list_path": "data.items",
  "cache_ttl": 300,
  "timeout": 10,
  "created_at": 1791191677,
  "updated_at": 1791191677
}

Feld	Beschreibung
slug	Name für data("…"); eindeutig über Collections und REST-Quellen
method	GET oder POST
url	Absolute http(s)-URL, darf Platzhalter enthalten
headers	Zusätzliche Request-Header (Platzhalter erlaubt). Accept: application/json wird immer gesetzt, bei Body auch Content-Type: application/json
body	JSON-Body für POST (Platzhalter erlaubt)
list_path	Punkt-Pfad zur Liste in der Antwort, z. B. data.items oder results.0.entries. Leer = gesamte Antwort
cache_ttl	Cache-Dauer in Sekunden, 0 = kein Cache. Standard 300
timeout	Timeout in Sekunden (1–60), Standard 10

Platzhalter

Syntax	Ersetzt durch
{name}	Parameter aus dem Template-Aufruf data("slug", "name", wert) bzw. Query-Parameter bei /data/{slug}?name=wert. In der URL URL-encodiert, im Body JSON-escaped, in Headern unverändert. Fehlende Parameter → leer
{env.NAME}	Umgebungsvariable NAME des Server-Prozesses – so bleiben Secrets aus der Datenbank heraus

Caching

Der Cache-Schlüssel besteht aus Methode, fertig expandierter URL und Body – unterschiedliche Parameter werden also getrennt gecacht. Der Cache liegt im Arbeitsspeicher und wird beim Ändern oder Löschen einer Quelle sowie beim Neustart geleert.

Fehlerverhalten

• HTTP-Status ≥ 400, ungültiges JSON, Timeout oder ein nicht auflösbarer list_path führen im Template zu einem Render-Fehler (Seite antwortet 500, Admins sehen Details) und bei /data/{slug} zu 502.
• Antworten über 10 MB werden abgeschnitten (→ ungültiges JSON).

Endpunkt	Zugriff	Beschreibung
GET /sources	🔑	Alle Quellen
GET /sources/{id}	🔑	Einzelne Quelle
POST /sources	✏️	Anlegen → 201
PUT /sources/{id}	✏️	Merge-Update; leert den Cache
DELETE /sources/{id}	✏️	Löschen → 204; leert den Cache
POST /sources/test	✏️	Konfiguration testen (siehe unten)

🔐 Wer REST-Quellen anlegen darf, kann den Server beliebige URLs abrufen lassen – auch im internen Netz. Vergib Schreib-Tokens entsprechend sparsam.

POST /sources/test ✏️

Führt eine (auch ungespeicherte) Konfiguration ohne Cache aus und liefert Rohdaten und extrahierte Liste – ideal zum Ermitteln des list_path.

{
  "method": "GET",
  "url": "https://shop.example.com/api/products?category={cat}",
  "headers": { "Authorization": "Bearer {env.SHOP_TOKEN}" },
  "list_path": "data.items",
  "params": { "cat": "schuhe" }
}

Antwort 200 (auch wenn der Abruf fehlschlägt – dann mit error):

{
  "result": {
    "status": 200,
    "url": "https://shop.example.com/api/products?category=schuhe",
    "duration_ms": 84,
    "data": [{ "name": "Sneaker", "price": 89.9 }],
    "raw": { "data": { "items": [{ "name": "Sneaker", "price": 89.9 }] } },
    "cached": false
  },
  "error": "remote source \"\": path \"data.items\": key \"items\" not found"
}

---