agorum core REST-API (Basis-Services)

Die Basis-Services sind die klassische REST-Schnittstelle von agorum core unter /api/rest. Mit ihnen suchen, lesen, erstellen, ändern und löschen Sie Objekte, laden Inhalte herunter und hoch und verwalten unter anderem Benutzer, Gruppen, ACLs, die MetaDB, Notizen und E-Mails.

Alle Services sind in einer Postman-Collection beschrieben, die Sie in Postman importieren und direkt ausprobieren können.

Voraussetzungen

---

• REST-Kenntnisse
• Verständnis für Objektstrukturen und Funktionen von agorum core
• ein Benutzer in agorum core, mit dem sich das aufrufende System anmeldet, in der Regel ein technischer Benutzer. Jeder Aufruf läuft mit den Rechten dieses Benutzers.

Postman-Collection

---

Die Collection enthält alle Basis-Services mit Beispielwerten und einer Beschreibung jedes Parameters:  agorum core REST API - basic services (Postman-Collection)

Verwendung in Postman

Gehen Sie wie folgt vor, um die Collection in Postman zu verwenden:

1. Installieren Sie Postman.
2. Laden Sie die Collection herunter.
3. Importieren Sie die Collection in Postman.
4. Tragen Sie in der Collection unter Variables > url die Adresse Ihres agorum core Servers ein, etwa https://mein-server.example.com.
5. Hinterlegen Sie die Anmeldedaten, siehe Authentifizierung:
   
   Standard: Tragen Sie unter Variables die Werte für username und password ein.
   JWT: Stellen Sie unter Authorization den Auth Type Bearer Token ein und tragen Sie das Token ein.
6. Testen Sie die Verbindung mit einer einfachen Anfrage, etwa object / read / object (search).

Basispfad und Datenformat

---

Alle Services liegen unter diesem Basispfad:

https://<agorum-core-server>/api/rest/...

Die Services antworten standardmäßig im Format XML. Um JSON zu erhalten, haben Sie zwei Möglichkeiten:

• Senden Sie den Header Accept: application/json. Die Postman-Collection tut das bei jeder Anfrage.
• Hängen Sie .json an den Pfad, etwa /api/rest/object.json.

Authentifizierung

---

Verfahren	Beschreibung
HTTP Basic	Benutzername und Kennwort werden bei jeder Anfrage mitgeschickt. Jede Anfrage meldet sich einzeln an. Das ist die Voreinstellung der Postman-Collection.
Session	POST /session meldet einen Benutzer an und liefert eine sessionId. Diese übergeben Sie bei den folgenden Aufrufen im Parameter sessionId. Nach zehn Minuten ohne Aufruf beendet das System die Session. DELETE /session meldet ab. Statt mit Benutzername und Kennwort können Sie sich auch mit einem Token anmelden, das ein Administrator mit POST /session/token erzeugt, siehe API Session Login über temporäres Token.
Bearer (JWT)	Ein JWT wird im Header Authorization: Bearer <Token> mitgeschickt. Das Token erzeugen Sie über Administration > Werkzeuge > JWT-Generator, siehe JWT-Generator.

Aufbau der Services

---

Die meisten Services teilen sich wenige Endpunkte. Welcher Service ausgeführt wird, bestimmt ein Parameter und nicht der Pfad:

Aktion	Aufruf
Lesen	GET /object mit provider=... oder GET /object/{id} mit handler=...
Erstellen	POST /object mit handler=...
Ändern	PUT /object/{id} mit updatehandler=...
Löschen	DELETE /object/{id} mit deletehandler=...

Die Anfragen der Postman-Collection sind nach diesem Wert benannt, etwa object (search) für GET /object?provider=search.

Parameter, die eine Struktur erwarten – data, parameters, sort und filter – übergeben Sie als JSON in einem einzelnen Formularfeld oder Query-Parameter. Mit dem wiederholbaren Parameter properties legen Sie fest, welche Eigenschaften die Antwort enthält. Lesende Services unterstützen außerdem start und limit zum Blättern.

Objekt-IDs

Wo eine ID erwartet wird, sind diese Formen möglich:

Form	Beispiel
Objekt-ID	123456
Objekt-Knoten-ID (für Bäume)	9999|654321|123456
Pfad	/agorum/roi/Files
UUID	uuid://1111-2222-3333-4444
Remote-ID	remoteid://remoteIdent;remoteId
Benutzer	user://roi
Gruppe	group://Demo

Rückgabewerte

---

Jede Antwort enthält die Felder success, errorClass, errorCode, errorKey und message. Lesende Services liefern zusätzlich total, data und meta, Services für ein einzelnes Objekt nur data.

errorClass	errorCode	Bedeutung
1	1	Anmeldung erforderlich
1	2	Zugriff verweigert (errorKey 1: Kontingent erreicht)
2	1	Objekt nicht gefunden
2	2	Objekt hat den falschen Typ
2	3	Parameter fehlt
2	4	Ungültiger Parameter
2	5	Konflikt
2	6	Zeitüberschreitung
3	1	Interner Serverfehler
3	2	Nicht implementiert
3	3	Unbekannter Fehler
3	4	Bad Gateway
3	5	Gateway Timeout

Übersicht der Services

---

Die Tabellen folgen der Ordnerstruktur der Postman-Collection. Die vollständige Beschreibung aller Parameter finden Sie in der Collection.

Session

Methode und Pfad	Beschreibung
POST /session	Meldet einen Benutzer an und liefert eine sessionId.
DELETE /session	Beendet die Session.
POST /session/transaction	Startet eine Transaktion und liefert eine transactionId. Aufrufe mit dieser ID werden sofort und in der Reihenfolge ihres Eingangs ausgeführt. Ihre Änderungen werden erst mit dem Abschluss der Transaktion dauerhaft oder beim Verwerfen zurückgenommen.
DELETE /session/transaction/{id}	Schließt eine Transaktion ab (rollback=false) oder verwirft sie (rollback=true).
POST /session/token	Erzeugt als Administrator ein Token für einen Benutzer (doAs), mit dem man sich an POST /session anmelden kann.

Objekte lesen

Aufruf	Beschreibung
GET /object?provider=search	Sucht Objekte über die Volltextsuche, siehe Suchsyntax in Solr verwenden.
GET /object?provider=searchcached	Sucht wie oben und hält das Ergebnis für weitere Seiten im Arbeitsspeicher. parameters muss cacheid (klein geschrieben) und duration (in ms) enthalten.
GET /object?provider=folder	Listet den Inhalt eines Ordners, wahlweise flach oder als Autovervollständigung.
GET /object/tree/{source}	Liefert einen Ordner mit seinen Unterobjekten als Baum bis zur angegebenen Tiefe.
GET /object/{id}	Liefert die Eigenschaften eines Objekts, mit handler=folder auch Ordnerinformationen.
GET /object?provider=parent	Liefert die übergeordneten Ordner eines Objekts.
GET /object?provider=history	Liefert die älteren Versionen eines Objekts.
GET /object?provider=relation	Liefert die Relationen eines Objekts zu einer Relationsklasse.
GET /object?provider=contenthash	Findet Objekte anhand eines Hash-Werts ihres Inhalts.
GET /object?provider=contenthashqueue	Listet Objekte, deren Hash-Wert noch berechnet wird.

Objekte erstellen, ändern und löschen

Aufruf	Beschreibung
POST /object mit handler=folder	Erstellt einen Ordner.
POST /object mit handler=object	Erstellt ein Objekt in einem Ordner, etwa ein FileObject.
PUT /object/{id} mit updatehandler=object	Ändert Eigenschaften eines Objekts.
DELETE /object/{id} mit deletehandler=object	Löscht ein Objekt oder verschiebt es mit {"trash":true} in den Papierkorb.

Inhalte

Aufruf	Beschreibung
GET /object/download/{id}	Lädt den Inhalt eines Objekts herunter. Ein Objekt ohne Inhalt, etwa ein Ordner, wird als ZIP-Datei seiner Inhalte geliefert.
GET /object/download/{id}/{format}	Lädt den Inhalt umgewandelt herunter, etwa .../pdf. Welche Formate möglich sind, hängt von den installierten Konvertern ab.
GET /object/download?ids=...&id=...	Lädt mehrere Objekte als eine ZIP-Datei herunter.
GET /object/embed/{id} GET /object/embed/{id}/{format}	Liefert den Inhalt zur Anzeige im Browser statt zum Download.
POST /object/upload	Lädt eine Datei in einen Zielordner hoch (Formularfeld body).
POST /object/upload/{id}	Lädt eine Datei als neue Version eines vorhandenen Objekts hoch.
POST /object/copyContent/{id}	Kopiert den Inhalt eines Objekts in ein anderes Objekt.

Versionen

Aufruf	Beschreibung
POST /object/checkout/{id}	Checkt ein Objekt aus. Dabei entsteht eine private Arbeitskopie.
POST /object/checkin/{id}	Checkt das Objekt oder die Arbeitskopie wieder ein und erzeugt eine neue Version.
POST /object/cancelCheckout/{id}	Bricht das Auschecken ab und löscht die Arbeitskopie.

Struktur und Relationen

Aufruf	Beschreibung
POST /object/move/{id}	Verschiebt Objekte in einen oder mehrere Zielordner.
POST /object/copy/{id}	Kopiert Objekte in einen oder mehrere Zielordner.
POST /object/link/{id}	Verknüpft ein Objekt mit einem oder mehreren Ordnern.
POST /object/relate/{id}	Erstellt Relationen zwischen einem Objekt und weiteren Objekten.
POST /object/unrelate/{id}	Entfernt solche Relationen wieder.

Papierkorb

Aufruf	Beschreibung
GET /object?provider=trashcan	Listet gelöschte Objekte im Papierkorb des Servers. Fragen Sie uuid als Eigenschaft mit ab – das Wiederherstellen benötigt sie.
POST /object/restore2/{id}	Stellt ein Objekt am ursprünglichen Ort oder in einem Zielordner wieder her. Konflikte lösen Sie mit rename oder merge.
POST /object/restore/{id}	Ältere Variante, abgelöst durch restore2.

Benutzer und Gruppen

Aufruf	Beschreibung
GET /object/{id}?handler=user	Liefert Informationen über einen Benutzer.
POST /object mit handler=user	Legt einen Benutzer an. Benutzername und eine E-Mail-Adresse sind Pflicht.
PUT /object/{id} mit updatehandler=user	Ändert die Daten eines Benutzers.
GET /object?provider=usergroupsearch	Sucht Benutzer und Gruppen.
GET /object?provider=groupmember	Listet die Mitglieder einer Gruppe.
GET /object?provider=appuserprofile	Liefert die Anwendungseinstellungen des angemeldeten Benutzers.
GET /object/{id}?handler=appuserprofile	Liefert eine einzelne Anwendungseinstellung.
POST /object mit handler=appuserprofile	Legt eine Anwendungseinstellung an oder aktualisiert sie.

ACLs, MetaDB und Konfiguration

Aufruf	Beschreibung
GET /object?provider=acl	Listet ACLs.
GET /object?provider=metadb	Liefert die Elemente eines MetaDB-Bundles. query wird nicht ausgewertet.
POST /object mit handler=metadb	Legt einen MetaDB-Eintrag an. Einen Service zum Löschen gibt es nicht.
GET /object?provider=quicksearch	Liefert die Konfiguration gespeicherter Schnellsuchen.
GET /object?provider=area	Liefert die Konfiguration gespeicherter Bereiche.
GET /object?provider=charset	Listet die vom Server unterstützten Zeichensätze.

Notizen und E-Mails

Aufruf	Beschreibung
GET /object?provider=note	Listet die Notizen eines Objekts.
POST /object mit handler=note	Erstellt eine Notiz an einem Objekt.
PUT /object/{id} mit updatehandler=note	Ändert eine Notiz.
POST /object mit handler=mail	Erstellt eine E-Mail im Postausgang oder als Entwurf.
GET /object?provider=mailrelation	Liefert die Relationen einer E-Mail.
GET /object?provider=mailattachment	Liefert die Anhänge einer E-Mail.
GET /object?provider=mailaddresssearch	Sucht E-Mail-Adressen, etwa von Benutzern, Kontakten und Verteilerlisten.
GET /object?provider=mailsenderaddress	Liefert die Absenderadressen des angemeldeten Benutzers.

Vorschau

Aufruf	Beschreibung
GET /object?provider=preview	Liefert je Seite der Vorschau die Abmessungen. Setzt eine vorhandene Master-Vorschau voraus.
GET /object/preview/{id}.jpg?page=1&size=400	Lädt das Vorschaubild einer Seite. Im Pfad steht die ID des Objekts mit der Endung .jpg, .jpeg oder .png; die Seite wählen Sie mit page.

DataHandler

Über GET /object?provider=data liefern die Services Daten einer in der MetaDB konfigurierten Quelle. Den MetaDB-Pfad der Konfiguration geben Sie in source an. Welcher DataHandler läuft, bestimmt der Eintrag Class dieses Bundles:

Class	Beschreibung
agorum.api.object.data.JdbcDataHandler	Daten aus einer SQL-Abfrage
agorum.api.object.data.CsvDataHandler	Zeilen aus einer CSV-Datei
agorum.api.object.data.SearchEngineTermsDataHandler	Begriffe aus einem Feld der Suchmaschine
agorum.api.object.data.UserDataHandler	Benutzer und ihre IDs

Die Einträge, die der jeweilige DataHandler in der MetaDB erwartet, sind in der Postman-Collection beschrieben.

GenericMultiQueue

Aufruf	Beschreibung
GET /object?provider=genericmultiqueue	Listet die Einträge einer Queue.
POST /genericMultiQueue/add/{id}	Fügt ein Objekt zu einer Queue hinzu.
DELETE /genericMultiQueue/remove/{id}	Entfernt ein Objekt aus einer Queue.

Weitere Informationen finden Sie unter Ergänzende Informationen für die Verwendung der Generic MultiQueue.