General
GET /api/groups
Returns a list of groups.
The following query string parameters can be used to filter, sort and paginate the returned list:
Query String Parameter | Type | Description |
---|---|---|
filter |
string |
A comma-separated list of filters to limit the results with (see Filtering). See the below table for the list of available filters |
sort |
string |
A comma-separated list of sort criteria (see Sorting). See the below table for the list of available sort criteria |
limit |
integer |
The maximum number of results to return (see Pagination) |
offset |
integer |
The index of the first result to return (see Pagination) |
The following filters are available:
Filter Name | Description |
---|---|
name |
Groups where the name specified in the metadata field match |
The list can be sorted by the following criteria:
Sort Criteria | Description |
---|---|
name |
By the group name |
description |
By the group description |
role |
By the group role |
members |
By the group members (only for api versions < 1.6.0) |
roles |
By the group roles (only for api versions < 1.6.0) |
Sample request
https://opencast.domain.com/api/groups?sort=name:ASC&limit=2&offset=1
Response
200 (OK)
: A (potentially empty) list of groups as JSON array of groups wheres the JSON objects representing groups
have the following fields:
Field | Type | Description |
---|---|---|
identifier |
string |
The identifier of the group |
role |
string |
The role of the group |
organization |
string |
The tenant identifier |
roles |
string |
The roles assigned to the group (comma-separated list) |
members |
string |
The list of users that belong to this group (comma-separated list of usernames) |
name |
string |
The name of the group |
description |
string |
The description of the group |
Example
[
{
"identifier": "MH_DEFAULT_ORG_SYSTEM_ADMINS",
"role": "ROLE_GROUP_MH_DEFAULT_ORG_SYSTEM_ADMINS",
"organization": "mh_default_org",
"roles": "ROLE_OAUTH_USER,ROLE_SUDO,ROLE_ADMIN,ROLE_ANONYMOUS",
"members": "admin,admin2",
"name": "Opencast Project System Administrators",
"description": "System administrators of 'Opencast Project'"
},
{
"identifier": "MH_DEFAULT_ORG_EXTERNAL_APPLICATIONS",
"role": "ROLE_GROUP_MH_DEFAULT_ORG_EXTERNAL_APPLICATIONS",
"organization": "mh_default_org",
"roles": "ROLE_EXAMPLE1,ROLE_EXAMPLE2,ROLE_EXAMPLE3",
"members": "apiuser",
"name": "Opencast Project External Applications",
"description": "External application users of 'Opencast Project'"
}
]
GET /api/groups/{group_id}
Returns a single group.
Response
200 (OK)
: The group is returned as JSON object with the following fields:
Field | Type | Description |
---|---|---|
identifier |
string |
The identifier of the group |
role |
string |
The role of the group |
organization |
string |
The tenant identifier |
roles |
string |
The roles assigned to the group (comma-separated list) |
members |
string |
The list of users that belong to this group (comma-separated list of usernames) |
name |
string |
The name of the group |
description |
string |
The description of the group |
404 (NOT FOUND)
: The specified group does not exist.
Example
{
"identifier": "MH_DEFAULT_ORG_SYSTEM_ADMINS",
"role": "ROLE_GROUP_MH_DEFAULT_ORG_SYSTEM_ADMINS",
"organization": "mh_default_org",
"roles": "ROLE_OAUTH_USER,ROLE_SUDO,ROLE_ADMIN,ROLE_ANONYMOUS",
"members": "admin,admin2",
"name": "Opencast Project System Administrators",
"description": "System administrators of 'Opencast Project'"
}
POST /api/groups
Creates a group.
Form Parameters | Required | Type | Description |
---|---|---|---|
name |
yes | string |
Group Name |
description |
no | string |
Group Description |
roles |
no | string |
Comma-separated list of roles |
members |
no | string |
Comma-separated list of members |
Response
This request does not return data.
201 (CREATED)
: A new group is created.
400 (BAD REQUEST)
: The request is invalid or inconsistent.
409 (CONFLICT)
: The group could not be created because a group with the same name already exists.
PUT /api/groups/{group_id}
Updates a group.
Form Parameters | Required | Type | Description |
---|---|---|---|
name |
yes | string |
Group Name |
description |
no | string |
Group Description |
roles |
no | string |
Comma-separated list of roles |
members |
no | string |
Comma-separated list of members |
If any of form parameters are ommited, the respective fields of the group will not be changed.
Response
This request does not return data.
200 (OK)
: The group has been updated.
404 (NOT FOUND)
: The specified group does not exist.
DELETE /api/groups/{group_id}
Deletes a group.
Response
This request does not return data.
204 (NO CONTENT)
: The group has been deleted.
404 (NOT FOUND)
: The specified group does not exist.
Members
POST /api/groups/{group_id}/members
Adds a member to a group.
Form Parameters | Required | Type | Description |
---|---|---|---|
member |
yes | string |
The username of the member to be added |
Response
200 (OK)
: The member has been added or was already member of the group.
If the member has been added, the request does not return data. In case that the member already was in the group, the following message is returned as string:
Member is already member of group
404 (NOT FOUND)
: The specified group does not exist.
DELETE /api/groups/{group_id}/members/{member_id}
Removes a member from a group
Response
200 (NO CONTENT)
: The member has been removed.
404 (NOT FOUND)
: The specified group or member does not exist.