Groups

Available groups in a Plone site can be created, queried, updated and deleted by interacting with the /@groups endpoint on portal root (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


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", 
    "title": "Administrators"
  }, 
  {
    "@id": "http://localhost:55001/plone/@groups/Reviewers", 
    "description": "", 
    "email": "", 
    "groupname": "Reviewers", 
    "id": "Reviewers", 
    "title": "Reviewers"
  }, 
  {
    "@id": "http://localhost:55001/plone/@groups/Site Administrators", 
    "description": "", 
    "email": "", 
    "groupname": "Site Administrators", 
    "id": "Site Administrators", 
    "title": "Site Administrators"
  }, 
  {
    "@id": "http://localhost:55001/plone/@groups/ploneteam", 
    "description": "We are Plone", 
    "email": "ploneteam@plone.org", 
    "groupname": "ploneteam", 
    "id": "ploneteam", 
    "title": "Plone Team"
  }, 
  {
    "@id": "http://localhost:55001/plone/@groups/AuthenticatedUsers", 
    "description": "Automatic Group Provider", 
    "email": "", 
    "groupname": "AuthenticatedUsers", 
    "id": "AuthenticatedUsers", 
    "title": "Authenticated Users (Virtual Group)"
  }
]

The endpoint supports some basic filtering:

http


The server will respond with a list the filtered groups in the portal with groupname starts with the query.

The endpoint also takes a limit parameter that defaults to 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", 
    "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


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 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", 
  "title": "Framework Team", 
  "users": {
    "@id": "http://localhost:55001/plone/@groups", 
    "items": [
      "Administrators", 
      "admin", 
      "test_user_1_"
    ], 
    "items_total": 3
  }
}

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


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", 
  "title": "Plone Team", 
  "users": {
    "@id": "http://localhost:55001/plone/@groups/ploneteam", 
    "items": [], 
    "items_total": 0
  }
}

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


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


A successful response will be indicated by a 204 No Content response:

HTTP/1.1 204 No Content