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.