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.