Groups
Contents
Groups#
Available groups in a Plone site can be created, queried, updated, and deleted by interacting with the /@groups
endpoint on the portal root.
This requires an authenticated user.
List Groups#
To retrieve a list of all current groups in the portal, call the /@groups
endpoint with a GET
request:
GET /plone/@groups HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
curl -i -X GET http://nohost/plone/@groups -H "Accept: application/json" --user admin:secret
http http://nohost/plone/@groups Accept:application/json -a admin:secret
requests.get('http://nohost/plone/@groups', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))
The server will respond with a list of all groups in the portal:
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"@id": "http://localhost:55001/plone/@groups/Administrators",
"description": "",
"email": "",
"groupname": "Administrators",
"id": "Administrators",
"members": {
"@id": "http://localhost:55001/plone/@groups",
"items": [],
"items_total": 0
},
"roles": [
"Manager",
"Authenticated"
],
"title": "Administrators"
},
{
"@id": "http://localhost:55001/plone/@groups/Reviewers",
"description": "",
"email": "",
"groupname": "Reviewers",
"id": "Reviewers",
"members": {
"@id": "http://localhost:55001/plone/@groups",
"items": [],
"items_total": 0
},
"roles": [
"Reviewer",
"Authenticated"
],
"title": "Reviewers"
},
{
"@id": "http://localhost:55001/plone/@groups/Site Administrators",
"description": "",
"email": "",
"groupname": "Site Administrators",
"id": "Site Administrators",
"members": {
"@id": "http://localhost:55001/plone/@groups",
"items": [],
"items_total": 0
},
"roles": [
"Site Administrator",
"Authenticated"
],
"title": "Site Administrators"
},
{
"@id": "http://localhost:55001/plone/@groups/ploneteam",
"description": "We are Plone",
"email": "ploneteam@plone.org",
"groupname": "ploneteam",
"id": "ploneteam",
"members": {
"@id": "http://localhost:55001/plone/@groups",
"items": [
"noam"
],
"items_total": 1
},
"roles": [
"Authenticated"
],
"title": "Plone Team"
},
{
"@id": "http://localhost:55001/plone/@groups/AuthenticatedUsers",
"description": "Automatic Group Provider",
"email": "",
"groupname": "AuthenticatedUsers",
"id": "AuthenticatedUsers",
"members": {
"@id": "http://localhost:55001/plone/@groups",
"items": [],
"items_total": 0
},
"roles": [],
"title": "Authenticated Users (Virtual Group)"
}
]
The endpoint supports some basic filtering:
GET /plone/@groups?query=plo HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
curl -i -X GET 'http://nohost/plone/@groups?query=plo' -H "Accept: application/json" --user admin:secret
http 'http://nohost/plone/@groups?query=plo' Accept:application/json -a admin:secret
requests.get('http://nohost/plone/@groups?query=plo', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))
The server will respond with a list of the filtered groups in the portal where groupname
starts with the value of the query
parameter.
The endpoint also takes a limit
parameter.
Its default is a maximum of 25 groups at a time for performance reasons:
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"@id": "http://localhost:55001/plone/@groups/ploneteam",
"description": "We are Plone",
"email": "ploneteam@plone.org",
"groupname": "ploneteam",
"id": "ploneteam",
"roles": [
"Authenticated"
],
"title": "Plone Team"
}
]
Create Group#
To create a new group, send a POST
request to the global /@groups
endpoint with a JSON representation of the group you want to create in the body:
POST /plone/@groups HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json
{
"description": "The Plone Framework Team",
"email": "fwt@plone.org",
"groupname": "fwt",
"groups": [
"Administrators"
],
"roles": [
"Manager"
],
"title": "Framework Team",
"users": [
"admin",
"test_user_1_"
]
}
curl -i -X POST http://nohost/plone/@groups -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"description": "The Plone Framework Team", "email": "fwt@plone.org", "groupname": "fwt", "groups": ["Administrators"], "roles": ["Manager"], "title": "Framework Team", "users": ["admin", "test_user_1_"]}' --user admin:secret
echo '{
"description": "The Plone Framework Team",
"email": "fwt@plone.org",
"groupname": "fwt",
"groups": [
"Administrators"
],
"roles": [
"Manager"
],
"title": "Framework Team",
"users": [
"admin",
"test_user_1_"
]
}' | http POST http://nohost/plone/@groups Accept:application/json Content-Type:application/json -a admin:secret
requests.post('http://nohost/plone/@groups', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'description': 'The Plone Framework Team', 'email': 'fwt@plone.org', 'groupname': 'fwt', 'groups': ['Administrators'], 'roles': ['Manager'], 'title': 'Framework Team', 'users': ['admin', 'test_user_1_']}, auth=('admin', 'secret'))
Note
By default, groupname
is a required field.
If the group has been created successfully, the server will respond with a status 201 Created. The Location
header contains the URL of the newly created group, and the resource representation is in the payload:
HTTP/1.1 201 Created
Content-Type: application/json
Location: http://localhost:55001/plone/@groups/fwt
{
"@id": "http://localhost:55001/plone/@groups/fwt",
"description": "The Plone Framework Team",
"email": "fwt@plone.org",
"groupname": "fwt",
"id": "fwt",
"members": {
"@id": "http://localhost:55001/plone/@groups",
"items": [
"Administrators",
"admin",
"test_user_1_"
],
"items_total": 3
},
"roles": [
"Manager",
"Authenticated"
],
"title": "Framework Team"
}
Read Group#
To retrieve all details for a particular group, send a GET
request to the /@groups
endpoint and append the group ID to the URL:
GET /plone/@groups/ploneteam HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
curl -i -X GET http://nohost/plone/@groups/ploneteam -H "Accept: application/json" --user admin:secret
http http://nohost/plone/@groups/ploneteam Accept:application/json -a admin:secret
requests.get('http://nohost/plone/@groups/ploneteam', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))
The server will respond with a 200 OK status code and the JSON representation of the group in the body:
HTTP/1.1 200 OK
Content-Type: application/json
{
"@id": "http://localhost:55001/plone/@groups/ploneteam",
"description": "We are Plone",
"email": "ploneteam@plone.org",
"groupname": "ploneteam",
"id": "ploneteam",
"members": {
"@id": "http://localhost:55001/plone/@groups/ploneteam",
"items": [
"noam"
],
"items_total": 1
},
"roles": [
"Authenticated"
],
"title": "Plone Team"
}
Batching is supported for the users
object.
Update Group#
To update the settings of a group, send a PATCH
request with the group details you want to amend to the URL of that particular group:
PATCH /plone/@groups/ploneteam HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json
{
"description": "Plone team members",
"email": "ploneteam2@plone.org",
"groups": [
"Site Administrators"
],
"roles": [
"Authenticated",
"Reviewer"
],
"title": "The Plone team",
"users": {
"test_user_1_": false
}
}
curl -i -X PATCH http://nohost/plone/@groups/ploneteam -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"description": "Plone team members", "email": "ploneteam2@plone.org", "groups": ["Site Administrators"], "roles": ["Authenticated", "Reviewer"], "title": "The Plone team", "users": {"test_user_1_": false}}' --user admin:secret
echo '{
"description": "Plone team members",
"email": "ploneteam2@plone.org",
"groups": [
"Site Administrators"
],
"roles": [
"Authenticated",
"Reviewer"
],
"title": "The Plone team",
"users": {
"test_user_1_": false
}
}' | http PATCH http://nohost/plone/@groups/ploneteam Accept:application/json Content-Type:application/json -a admin:secret
requests.patch('http://nohost/plone/@groups/ploneteam', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'description': 'Plone team members', 'email': 'ploneteam2@plone.org', 'groups': ['Site Administrators'], 'roles': ['Authenticated', 'Reviewer'], 'title': 'The Plone team', 'users': {'test_user_1_': False}}, auth=('admin', 'secret'))
Note
The users
object is a mapping of a user_id
and a boolean indicating adding or removing from the group.
A successful response to a PATCH
request will be indicated by a 204 No Content response:
HTTP/1.1 204 No Content
Delete Group#
To delete a group, send a DELETE
request to the /@groups
endpoint and append the group id of the group you want to delete:
DELETE /plone/@groups/ploneteam HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
curl -i -X DELETE http://nohost/plone/@groups/ploneteam -H "Accept: application/json" --user admin:secret
http DELETE http://nohost/plone/@groups/ploneteam Accept:application/json -a admin:secret
requests.delete('http://nohost/plone/@groups/ploneteam', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))
A successful response will be indicated by a 204 No Content response:
HTTP/1.1 204 No Content