Für Entwickler

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

Basis-Pfad/_/api/<resource>/… — die Endpunkte liegen unter /_/, damit sie nie mit einer Seite kollidieren.

FormatAnfragen und Antworten in JSON (Content-Type: application/json).

AuthHeader X-Orb-Token und X-Orb-Secret.

RechteJede Operation wird gegen die granularen Rechte des API-Zugangs geprüft.

CORSAktiviert (Access-Control-Allow-Origin: *); OPTIONS liefert 204.

Authentifizierung

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

TokenÖffentlicher Bezeichner, Form orb_<hex>. Dient dem Nachschlagen des Zugangs.

SecretGeheimnis, Form sk_<hex>. Wird nur einmal bei der Erstellung angezeigt und intern nur als gesalzener SHA-256-Hash gespeichert.

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

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

Secret sicher aufbewahren

Das Secret kann nach der Erstellung nicht erneut angezeigt werden. Bewahre es sicher auf (z. B. in einem Passwort-Tresor). Geht es verloren, erzeuge einen neuen Zugang. Ein deaktivierter/gesperrter Zugang kann sich nicht mehr authentifizieren.

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_..."

Konventionen

Methode	Bedeutung
GET	Lesen (Liste oder einzelnes Objekt)
POST	Neu anlegen
PUT	Ersetzen (kompletter Datensatz)
PATCH	Zusammenführen (nur gelieferte Felder)
DELETE	Löschen (bei Inhalten „weich“)

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

GET/_/api/collections

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

GET/_/api/collections/{cid}/records

Listet die Datensätze einer Sammlung.

POST/_/api/collections/{cid}/records

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" } }'

GET/_/api/collections/{cid}/records/{rid}

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

PUTPATCH/_/api/collections/{cid}/records/{rid}

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

DELETE/_/api/collections/{cid}/records/{rid}

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

Seiten

GET/_/api/pages

Listet alle Seiten (id, link, data).

POST/_/api/pages

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.

GETPUTPATCHDELETE/_/api/pages/{pid}

Lesen, ersetzen, zusammenführen oder (weich) 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.

GET/_/api/media

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

GET/_/api/media/{fileId}

Metadaten einer einzelnen Datei.

POST/_/api/media

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"

PUTPATCH/_/api/media/{fileId}

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

DELETE/_/api/media/{fileId}

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

Ordner

GET/_/api/folders

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

POST/_/api/folders

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

PUTPATCH/_/api/folders/{id}

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

DELETE/_/api/folders/{id}

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

Benutzer

GET/_/api/users

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

POST/_/api/users

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"] }
  }
}

GETPUTPATCHDELETE/_/api/users/{id}

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

Rechte gelten auch für die API

Ein 403 Forbidden bedeutet, dass der API-Zugang für diese Operation keine Berechtigung hat — nicht, dass der Endpunkt fehlt. Prüfe die granularen Rechte des Zugangs.

Fehlerformat

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

{ "error": "Forbidden" }