Groups and roles¶
Manage groups and roles.
Managing groups¶
List all groups/roles¶
-
GET
/group
¶ Returns list of all groups.
Query Parameters: - first (integer) – Start returning groups from specified number. Default is
1
, the beginning of the list. - number (integer) – Return at most specified number of groups. Default is no limit.
- role (boolean) –
true
- Return only roles.false
- Return only regular groups.
Default is to return all.
New in version 4.16.
Produces: - application/xml, application/json – GroupListDocument
- text/plain – CRLF-delimited list of group URIs
Role: _group_read
- first (integer) – Start returning groups from specified number. Default is
Retrieve a group/role¶
-
GET
/group/
(group-name)¶ Returns information about the specified group.
Produces: - application/xml, application/json – GroupDocument
- text/plain – The URI to the group.
Role: _group_read
Retrieve role status¶
-
GET
/group/
(group-name)/role
¶ Returns the role status of the specified group.
Produces: - text/plain – 1 if group is a role, 0 if group is a regular group
Role: _group_read
Create a group¶
-
PUT
/group/
(group-name)¶ Creates a new group with the specified name.
Status Codes: - 200 OK – Group created.
- 409 Conflict – A group with that name already exists.
Role: _group_write
Update or create a group¶
-
PUT
/group/
(group-name)¶ Creates or updates the group with the specified name. Also any specified parent and child associations, users, metadata and description will be added.
Query Parameters: - clear (boolean) –
true
- Remove any existing groups and users not in the given document.false
(default) - Existing groups and users not in the request document will be kept as is.
Status Codes: - 200 OK – Group created.
Accepts: - application/xml, application/json – GroupDocument
Role: _group_write
- clear (boolean) –
Delete a group¶
-
DELETE
/group/
(group-name)¶ Deletes the group with the specified name.
Role: _group_write
Delete multiple groups¶
-
DELETE
/group
¶ Deletes the groups with the specified names.
Query Parameters: - name (string) – Required. Comma-separated list of group names.
Role: _group_write
Example¶
DELETE /group?name=teachers,students,guests
Search for groups¶
-
PUT
/group
¶ Simple search of fields
groupname
,description
and metadata.Query Parameters: - first (integer) – Start returning groups from specified number. Default is
1
, the beginning of the list. - number (integer) – Return at most specified number of groups. Default is
10
. - role (boolean) –
true
- Return only roles.false
- Return only regular groups.
Default is to return all.
Accepts: - application/xml, application/json – GroupSearchDocument
Produces: - application/xml, application/json – GroupListDocument
- text/plain – CRLF-delimited list of group names
- first (integer) – Start returning groups from specified number. Default is
Example¶
PUT /group
Content-Type: application/xml
<GroupSearchDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<field>
<name>groupname</name>
<value>vidi</value>
</field>
<field>
<name>key</name>
<value>value</value>
</field>
</GroupSearchDocument>
Note that keywords groupname
and description
are reserved to do search on
groupname
and description
fields
The boolean operators AND and OR are supported:
<GroupSearchDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<field>
<name>groupname</name>
<value>vidi</value>
</field>
<field>
<name>description</name>
<value>vidispine</value>
</field>
<operator operation="OR">
<field>
<name>key1</name>
<value>value1</value>
</field>
<field>
<name>key2</name>
<value>value2</value>
</field>
</operator>
</GroupSearchDocument>
Group information¶
Group-to-group relations¶
List all parent groups to a group¶
-
GET
/group/
(group-name)/parents
¶ Returns groups that the specified group belongs to.
Query Parameters: - traverse (boolean) –
true
- Return all ancestors.false
(default) - Return only direct parents.
Produces: - application/xml, application/json – GroupListDocument
- text/plain – CRLF-delimeted list of URIs to the groups
Role: _group_read
- traverse (boolean) –
List all child groups to a group¶
-
GET
/group/
(group-name)/children
¶ Returns groups that belongs to the specified group.
Query Parameters: - traverse (boolean) –
true
- Return all descendants.false
(default) - Return only direct children.
Produces: - application/xml, application/json – GroupListDocument
- text/plain – CCRLF-delimeted list of URIs to the groups
Role: _group_read
- traverse (boolean) –
Group-to-user relations¶
List all users in a group¶
-
GET
/group/
(group-name)/users
¶ Returns all users belonging to the group/role, directly or indirectly.
Query Parameters: - traverse (boolean) –
true
- Return all users, including users in child groups.false
(default) - Return only direct users.
Produces: - application/xml, application/json – UserListDocument
- text/plain – CRLF-delimeted list of Tabbed tuples of user name, user real name
Role: _group_read
- traverse (boolean) –