Referenz: Gruppen, Märkte, Zugriff

Das Gruppen-Objekt

Gruppen anlegen, umbenennen und löschen braucht eine Administratorin oder einen Administrator als Person des Schlüssels, wie unter Einstellungen › Gruppen. Mitglieder verwaltet die API nicht — sie kommen aus dem CMS, dem Single Sign-on oder einem Verzeichnis.

GET /groups · GET /groups/{id} · GET /groups/ref/{ref}

Berechtigung Lesen. Alle Gruppen nach Namen, { "data": Group[] } — oder eine.

POST /groups · PUT /groups/ref/{ref}

Berechtigung Schreiben. Inhalt { "name": "…", "description": "…" }. POST antwortet 201; PUT über die Referenz legt an (201) oder aktualisiert (200), dieselbe Anfrage zweimal ergibt also eine Gruppe. Ein Name, den eine andere Gruppe hat, ist 409.

PATCH /groups/{id} · PATCH /groups/ref/{ref}

Berechtigung Schreiben. Umbenennen oder die Beschreibung ändern.

DELETE /groups/{id} · DELETE /groups/ref/{ref}

Berechtigung Schreiben. 204. Ihre Mitgliedschaften gehen mit, ebenso jede Berechtigung, die sie hatte.

Märkte

Ein Markt ist ein Land: Sein code (DE, AT) ist der Schlüssel jedes titles-Objekts und ändert sich nicht. { "id", "code", "name", "locale", "isDefault" }. Schreiben braucht eine Administratorin oder einen Administrator als Person des Schlüssels, wie unter Einstellungen › Märkte.

GET /markets · GET /markets/{code}

Berechtigung Lesen. Alle Märkte nach Code, { "data": Market[] } — oder einer. GET /markets nennt jetzt auch die id jedes Markts.

POST /markets

Berechtigung Schreiben. { "code": "AT" } legt den Markt für ein Land an — 201, oder 200 mit dem Markt, den es schon gibt.

PATCH /markets/{code}

Berechtigung Schreiben. { "name": "Österreich", "isDefault": true } — eines oder beides. Wird ein Markt zum Standard, endet es für den bisherigen.

DELETE /markets/{code}

Berechtigung Schreiben. 204. Entfernt den Markt und jeden Titel in ihm; war es der Standard, übernimmt der nächste nach Code.

Zugriff

Wer eine Kategorie oder ein Dokument lesen darf, entscheiden Berechtigungen: eine Gruppe oder eine Person und eine Stufe — read, full oder none. Die Berechtigungen einer Kategorie gelten für alles darunter, bis eine weiter unten etwas anderes sagt; none nimmt weg, was eine Kategorie darüber gibt. Die eigenen Berechtigungen eines Dokuments sind Ausnahmen von dem, was seine Kategorien geben.

Das Zugriffs-Objekt

{
  "grants": [
    { "groupId": "3f2c…", "groupRef": "REGION-NORD", "level": "read", "inherited": false },
    { "userEmail": "anna@example.com", "level": "full", "inherited": true }
  ]
}

inherited (nur bei Kategorien) kennzeichnet eine Berechtigung, die auf einer Kategorie darüber gesetzt ist, nicht auf dieser.

GET /categories/{id}/access · GET /categories/ref/{ref}/access

GET /documents/{id}/access · GET /documents/ref/{ref}/access

Berechtigung Lesen, und volle Rechte der Person des Schlüssels auf die Kategorie oder das Dokument.

PUT /categories/{id}/access · PUT /categories/ref/{ref}/access

PUT /documents/{id}/access · PUT /documents/ref/{ref}/access

Berechtigung Schreiben, volle Rechte. Der Inhalt ist die ganze Menge der ausdrücklichen Berechtigungen — wer fehlt, hat hier keine und erbt:

{
  "grants": [
    { "groupRef": "REGION-NORD", "level": "read" },
    { "userEmail": "anna@example.com", "level": "full" }
  ]
}

Jede Berechtigung nennt genau einen Empfänger: groupId, groupRef oder userEmail (ein Mitglied der Organisation). Eine unbekannte Referenz oder Adresse ist 400 und wird in issues genannt.

Bei einem Dokument macht "restrictToGrantedUsers": true es nur für die genannten Personen lesbar: Jede Gruppe, die seine Kategorien hereinlassen würden, bekommt none. Das gilt für die Gruppen, die es beim Senden erreichen — eine Gruppe, die später Zugriff auf die Kategorie bekommt, wird nicht zurückgehalten.