REST API

Die Orblio-API ist eine externe, Token-authentifizierte Schnittstelle. Damit liest und schreibst du Sammlungen, Seiten, Medien, Ordner und Benutzer aus eigenen Programmen — im JSON-Format über HTTP.

Überblick

Authentifizierung

Ein API-Zugang ist ein Benutzer mit der Rolle API (siehe Team & Rechte). Bei der Erstellung erhältst du zwei Werte:

Beide Werte gehören in jede Anfrage — als HTTP-Header:

X-Orb-Token:  orb_1a2b3c4d5e6f...
X-Orb-Secret: sk_9f8e7d6c5b4a...

Fehlen die Header oder passen Token/Secret nicht zusammen, antwortet die API mit 401:

{ "error": "Invalid or missing API credentials" }

Erstes Beispiel

curl https://deine-domain.ch/_/api/collections \
  -H "X-Orb-Token: orb_..." \
  -H "X-Orb-Secret: sk_..."

PHP-Client (zum Download)

Damit du nicht jeden Aufruf von Hand zusammenbaust, gibt es einen schlanken, abhängigkeitsfreien PHP-Client: die Klasse OrblioApiClient. Sie kümmert sich um Authentifizierung, JSON, Fehlerbehandlung, Timeouts, optionale Wiederholungen und Datei-Uploads — und bietet für jede Ressource fertige Methoden.

⬇  api.php herunterladen   Quelltext ansehen

Schnellstart

<?php
require_once __DIR__ . '/api.php';

/* Token, Secret und Domain — den Pfad /_/api hängt der Client selbst an */
$api = new OrblioApiClient('orb_...', 'sk_...', 'https://deine-domain.ch');

/* Seiten auflisten */
$pages = $api->listPages();

/* Datensatz in Sammlung 3 anlegen und die neue ID lesen */
$id = $api->createRecord(3, ['name' => 'Maria Muster', 'role' => 'Vorstand'])['id'];

Zugangsdaten lassen sich auch fluent oder über Umgebungsvariablen (ORBLIO_API_TOKEN, ORBLIO_API_SECRET) setzen:

$api = (new OrblioApiClient())
    ->setBaseUrl('https://deine-domain.ch')
    ->setCredentials('orb_...', 'sk_...')
    ->setTimeout(15)
    ->setMaxRetries(2);

Methoden im Überblick

Für jede Ressource gibt es benannte Methoden — alle geben das dekodierte JSON als Array zurück:

Konfiguration

Fehlerbehandlung

Der Client wirft sprechende Exceptions statt stiller Fehlercodes:

try {
    $rec = $api->getRecord(3, 42);
} catch (OrblioApiException $e) {
    /* HTTP-Fehler von der API — z. B. 403 oder 404 */
    error_log($e->getStatusCode() . ': ' . $e->getMessage());
} catch (OrblioTransportException $e) {
    /* Server nicht erreichbar */
    error_log('Verbindung fehlgeschlagen: ' . $e->getMessage());
}

Datei hochladen

/* Lädt eine lokale Datei hoch (optional in einen Ordner) */
$file = $api->uploadMedia('/pfad/zu/bild.jpg', $folderId = null);
echo $file['url'];   /* öffentliche Adresse der Datei */

Endpunkte direkt ansprechen

Wer keinen PHP-Client nutzt (oder eine andere Sprache verwendet), spricht die Endpunkte direkt an. Die folgende Referenz beschreibt sie vollständig.

Konventionen

Statuscodes: 200 OK · 201 Erstellt · 204 (OPTIONS) · 400 Fehlerhafte Anfrage · 401 Nicht authentifiziert · 403 Keine Berechtigung · 404 Nicht gefunden · 405 Methode nicht erlaubt · 500 Serverfehler.

Nutzdaten für Datensätze werden im Feld data übergeben. Kontrollspalten (cId, cParent, cDel, cDate) kann ein Client nie setzen — sie werden serverseitig entfernt.

Sammlungen

Listet alle Sammlungs-Definitionen (id, name, fields).

Listet die Datensätze einer Sammlung.

Legt einen Datensatz an. Body: { "data": { … } }. Antwort 201 mit id und data. Löst den Webhook collections.create aus.

curl -X POST https://deine-domain.ch/_/api/collections/3/records \
  -H "X-Orb-Token: orb_..." -H "X-Orb-Secret: sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "data": { "name": "Maria Muster", "role": "Vorstand" } }'

Liest einen einzelnen Datensatz (mit id, data, date, update).

PUT ersetzt das data vollständig, PATCH führt es mit dem bestehenden zusammen. Löst collections.update aus.

Weiches Löschen (cDel = 1). Antwort { "id": …, "deleted": true }. Löst collections.delete aus.

Seiten

Listet alle Seiten (id, link, data).

Legt eine Seite an. Body: { "link": "neue-seite", "data": { … } }. Der Link wird bereinigt (nur a–z A–Z 0–9 _ - /). Fehlt content in data, wird es leer angelegt. Löst pages.create aus.

Lesen, ersetzen, zusammenführen oder löschen. Bei PUT/PATCH lässt sich optional der link mitändern. Auslösende Webhooks: pages.update, pages.delete.

Medien

Medien-Endpunkte sind ordnerunabhängig: Lese- und Änderungszugriffe suchen die Datei über alle Ordner hinweg.

Listet alle Dateien (über alle Ordner). Jede Datei liefert id, folder, name, title, description, type, url.

Metadaten einer einzelnen Datei.

Datei hochladen — als multipart/form-data mit dem Feld file (optional folder). Löst media.create aus.

curl -X POST https://deine-domain.ch/_/api/media \
  -H "X-Orb-Token: orb_..." -H "X-Orb-Secret: sk_..." \
  -F "file=@bild.jpg" -F "folder=root"

Metadaten ändern: title, description, credits, creator, name. Werte werden von HTML befreit. Löst media.update aus.

Datei löschen. Löst media.delete aus.

Ordner

Listet Ordner (id, name, type, Anzahl files).

Ordner anlegen. Body: { "name": "…" }.

Ordner umbenennen. Body: { "name": "…" }.

Ordner löschen. Nicht destruktiv: enthaltene Dateien wandern zurück ins Wurzelverzeichnis (Antwort enthält filesMovedToRoot).

Benutzer

Listet Benutzer (id, email, role, active, permissions).

Benutzer anlegen. Pflicht: email, password. Optional: role (admin, editor, viewer, api — Standard editor), pages, permissions, active. Ohne permissions werden rollenbasierte Standardrechte gesetzt. Löst users.create aus.

{
  "email": "redaktion@beispiel.ch",
  "password": "ein-sicheres-passwort",
  "role": "editor",
  "pages": ["4", "7"],
  "permissions": {
    "pages": { "scope": "list", "ids": [4, 7], "ops": ["read", "update"] }
  }
}

Lesen, ändern oder deaktivieren. DELETE ist ein weiches Löschen (Login wird gesperrt, haslogin = -1), passend zum CMS-Verhalten. Webhooks: users.update, users.delete.

Fehlerformat

Fehler kommen immer als JSON mit einem error-Feld und passendem HTTP-Status:

{ "error": "Forbidden" }