API methods - groups

Create a group

To access this endpoint you must have groups.write permission.

The API does not accept a URN for a group. This will be generated based on the group name. For example if the group name is admin the URN will be urn:telicent:groups:admin.

POST /groups

Request body example:

{
  "name": "admin",
  "description": "Administrator group"
}

Responses:

Status: 200 - group created and returned

Response body example:

{
  "id": "9e815e51-e0ea-47c6-ab35-2cb312f8ee70",
  "urn": "urn:telicent:groups:admin",
  "name": "admin",
  "description": "Administrator group",
  "active": true
}

Status: 400 - group already exists

{
  "error": "Group already exists",
  "error_description": "A group with this name or URN already exists."
}

Delete a group

To access this endpoint you must have groups.write permission.

DELETE /groups/{groupId}

Responses:

Status: 204 - group deleted

Status: 404 - group not found

Get group by ID

To access this endpoint you must have groups.read permission.

GET /groups/{groupId}

Responses:

Status: 200 - group returned

Response body example:

{
  "id": "9e815e51-e0ea-47c6-ab35-2cb312f8ee70",
  "urn": "urn:telicent:groups:admin",
  "name": "admin",
  "description": "Administrator group",
  "active": true
}

Status: 404 - group not found

Get groups

To access this endpoint you must have groups.read permission.

GET /groups

Responses:

Status: 200 - all groups returned

Response body example:

{
  "total": 1,
  "groups": [
    {
      "id": "9e815e51-e0ea-47c6-ab35-2cb312f8ee70",
      "urn": "urn:telicent:groups:admin",
      "name": "admin",
      "description": "Administrator group",
      "active": true
    }
  ]
}

Update a group

To access this endpoint you must have groups.write permission. The group name and URN cannot be updated via this endpoint.

PUT /groups/{groupId}

Request body example:

{
  "description": "Admin",
  "active": false
}

Note that only the values to be updated need to be sent in the request.

Responses:

Status: 200 - group updated and returned Response body example:

{
  "id": "9e815e51-e0ea-47c6-ab35-2cb312f8ee70",
  "urn": "urn:telicent:groups:admin",
  "name": "Admin",
  "description": "Administrator group",
  "active": false
}

Status 404 - group not found