Groups Endpoint
Endpoint Overview
Group Operations:
GET: /admin/groups
: return all groupsGET: /admin/groups/<groupIri>
: return single group identified by [IRI]POST: /admin/groups
: create a new groupPUT: /admin/groups/<groupIri>
: update groups's basic informationPUT: /admin/groups/<groupIri>/status
: update group's statusDELETE: /admin/groups/<groupIri>
: delete group (set status to false)
Member Operations:
GET: /admin/groups/<groupIri>/members
: return all group members
Group Operations
Create Group
- Required permission: SystemAdmin / hasProjectAllAdminPermission / hasProjectAllGroupAdminPermission
- Required information: name (unique inside project), project IRI
- Optional information: group descriptions
- Returns information about the newly created group
- POST:
/admin/groups
- BODY:
{
"name": "NewGroup",
"descriptions": [
{
"value": "NewGroupDescription",
"language": "en"
},
{
"value": "NeueGruppenBeschreibung",
"language": "de"
}
],
"project": "http://rdfh.ch/projects/00FF",
"status": true,
"selfjoin": false
}
Additionally, each group can have an optional custom IRI (of @ref:Knora IRI
form)
specified by the id
in the request body as below:
{
"id": "http://rdfh.ch/groups/00FF/a95UWs71KUklnFOe1rcw1w",
"name": "GroupWithCustomIRI",
"descriptions": [
{
"value": "A new group with a custom IRI",
"language": "en"
}
],
"project": "http://rdfh.ch/projects/00FF",
"status": true,
"selfjoin": false
}
Update group information
- Required permission: SystemAdmin / hasProjectAllAdminPermission / hasProjectAllGroupAdminPermission / hasProjectRestrictedGroupAdminPermission (for this group)
- Changeable information:
name
,descriptions
,selfjoin
- TypeScript Docs: groupFormats - ChangeGroupApiRequestADM
- PUT:
/admin/groups/<groupIri>
- BODY:
{
"name": "UpdatedGroupName",
"descriptions": [
{
"value": "UpdatedGroupDescription",
"language": "en"
}
],
"selfjoin": false
}
Change Group Status
- Required permission: SystemAdmin / hasProjectAllAdminPermission
- Changeable information:
status
- Remark: Deleting a group, removes all members from the group.
- PUT:
/admin/groups/<groupIri>/status
- BODY:
{
"status": false
}
Delete Group
- Required permission: SystemAdmin / hasProjectAllAdminPermission
- Remark: The same as changing the groups
status
tofalse
. To un-delete, setstatus
totrue
. - DELETE:
/admin/groups/<groupIri>
Example Group Information stored in admin named graph: :
<http://rdfh.ch/groups/[shortcode]/[UUID]>
rdf:type knora-admin:UserGroup ;
knora-admin:groupName "Name of the group" ;
knora-admin:groupDescriptions "A description of the group"@en ;
knora-admin:belongsToProject <http://rdfh.ch/projects/[UUID]> ;
knora-admin:status "true"^^xsd:boolean ;
knora-admin:hasSelfJoinEnabled "false"^^xsd:boolean .
Member Operations
Get Group Members
- Returns all group members
- Required permission: SystemAdmin / ProjectAdmin
- GET:
/admin/groups/<groupIri>/members