Groups-API

Gruppen erstellen, lesen, aktualisieren und löschen über die REST-API

Geschrieben von Erdinc Akay

Zuletzt aktualisiert Vor 25 Tagen

Die Groups-API ermöglicht das Erstellen, Lesen, Aktualisieren und Löschen von Gruppen. Gruppen kombinieren ein Berechtigungsset mit einer Mitgliederliste — wird ein Benutzer einer Gruppe zugewiesen, erhält dieser die Berechtigungen der Gruppe.

Alle Endpoints erfordern ein gültiges JWT im Authorization: Bearer <token>-Header.

Die vollständige, stets aktuelle Liste der Endpoints, Parameter und Antwortfelder für die Version, die du betreibst, findest du in der interaktiven OpenAPI-Oberfläche (Swagger) unter https://<deine-octoja-instanz>/openapi/index.html.

Endpoints

OperationEndpointHinweise
Gruppen auflistenGET /api/groupsMit dem optionalen Parameter search nach Gruppenname filtern. Liefert ein Array von Group-Objekten zurück.
Eine Gruppe abrufenGET /api/groups/{id}Liefert 404 Not Found, wenn keine Gruppe mit der angegebenen id existiert.
Eine Gruppe erstellenPOST /api/groupsErfordert groups.manage. name ist erforderlich und muss mindestens ein Nicht-Leerzeichen enthalten; fehlende, leere oder ausschließlich aus Leerzeichen bestehende Werte werden mit 400 Bad Request abgelehnt. Liefert das erstellte Group-Objekt zurück.
Eine Gruppe aktualisierenPOST /api/groups/{id}Erfordert groups.manage. Verwendet die UpdateValue<T>-Hülle (siehe unten).
Eine Gruppe löschenDELETE /api/groups/{id}Erfordert groups.manage. Liefert 204 No Content (siehe unten).

Aktualisierungen erfolgen über POST /api/groups/{id}. PUT und PATCH sind für diese Ressource nicht registriert und liefern 404 Not Found zurück.

Wichtige Felder

  • isAdministratorGroup — kennzeichnet die Gruppe als Administratorgruppe. Führt ein octoja-Upgrade neue Berechtigungen ein, werden sie jeder Gruppe mit diesem Flag automatisch gewährt.

Eine Gruppe aktualisieren

Sende nur die zu ändernden Felder. Jedes Feld wird in eine UpdateValue<T>-Hülle der Form { "hasValue": true, "value": <T> } verpackt; lass das Feld komplett weg, um es unverändert zu lassen. Ein nackter Wert (zum Beispiel "newName": "Support") wird als Deserialisierungsfehler abgelehnt. newPermissions und newMemberUserIds ersetzen jeweils die vollständige Liste, statt sie zusammenzuführen.

{  "newName": { "hasValue": true, "value": "Support" },  "newPermissions": { "hasValue": true, "value": ["tickets.manage", "customers.manage"] }}

Validierung:

  • newName mit einem leeren oder ausschließlich aus Leerzeichen bestehenden value liefert 400 Bad Request.
  • Eine unbekannte Berechtigungs-ID in newPermissions liefert 400 Bad Request.
  • Eine unbekannte Benutzer-ID in newMemberUserIds liefert 400 Bad Request.
  • Das Entfernen der letzten effektiven groups.manage-Fähigkeit wird durch die Sicherheitsprüfung abgelehnt.

Eine Gruppe löschen

Beim Löschen einer Gruppe wird diese automatisch von allen Mitgliedern entfernt. Die Sicherheitsprüfung verhindert zudem das Löschen einer Gruppe, wenn dadurch keine Gruppe mehr zur Gruppenverwaltung übrig bliebe.

Verwandte Artikel