Groups

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:

http

GET /plone/@groups HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i -X GET http://nohost/plone/@groups -H "Accept: application/json" --user admin:secret

httpie

http http://nohost/plone/@groups Accept:application/json -a admin:secret

python-requests

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:

http

GET /plone/@groups?query=plo HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i -X GET 'http://nohost/plone/@groups?query=plo' -H "Accept: application/json" --user admin:secret

httpie

http 'http://nohost/plone/@groups?query=plo' Accept:application/json -a admin:secret

python-requests

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:

http

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

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

httpie

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

python-requests

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:

http

GET /plone/@groups/ploneteam HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i -X GET http://nohost/plone/@groups/ploneteam -H "Accept: application/json" --user admin:secret

httpie

http http://nohost/plone/@groups/ploneteam Accept:application/json -a admin:secret

python-requests

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:

http

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

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

httpie

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

python-requests

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:

http

DELETE /plone/@groups/ploneteam HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i -X DELETE http://nohost/plone/@groups/ploneteam -H "Accept: application/json" --user admin:secret

httpie

http DELETE http://nohost/plone/@groups/ploneteam Accept:application/json -a admin:secret

python-requests

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

Groups

Contents

Groups#

List Groups#

Create Group#

Read Group#

Update Group#

Delete Group#