Groups

Available groups 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:

GET /@groups HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

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:8000/@groups/Administrators",
    "description": "",
    "email": "",
    "groupname": "Administrators",
    "id": "Administrators",
    "roles": [
      "Administrator"
    ],
    "title": "Administrators"
  }
]

The endpoint supports some basic filtering:

GET /@groups?query=Administrators HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

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

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "@id": "http://localhost:8000/@groups/Administrators",
    "description": "",
    "email": "",
    "groupname": "Administrators",
    "id": "Administrators",
    "roles": [
      "Administrator"
    ],
    "title": "Administrators"
  }
]

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 /@groups HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk
Content-Type: application/json

{
  "groupname": "nicks",
  "title": "Nicks",
  "description": "Nearly Headless Nicks",
  "email": "nearly.headless.nicks@example.com",
  "roles": [
      "Contributor"
  ]
}

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

{
  "@id": "http://localhost:8000/@groups/nicks",
  "id": "nicks",
  "groupname": "nicks",
  "description": "Nearly Headless Nicks",
  "email": "nearly.headless.nicks@example.com",
  "roles": [],
  "title": "Nicks"
}

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 /@groups/Administrators HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

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:8000/@groups/Administrators",
  "id": "Administrators",
  "title": "Administrators",
  "description": "",
  "groupname": "Administrators",
  "email": "",
  "roles": [
    "Administrator"
  ]
}

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 /@groups/nicks HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk
Content-Type: application/json

{
  "title": "Headless Nicks"
}

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 /@groups/nicks HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

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

HTTP/1.1 204 No Content