Groups and roles¶
Managing groups¶
List groups/roles¶
-
GET
/group
¶ Returns list of all groups.
Query Parameters: - first – Start returning groups from specified number. Default is
1
, the beginning of the list. - number – Return at most specified number of groups. Default is no limit.
- role –
Set to true to only return roles, false to only return 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 – Start returning groups from specified number. Default is
Get 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
Get 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 new 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
Create or update 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 –
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 –
Delete a group¶
-
DELETE
/group/
(group-name)¶ Deletes the group with the specified name.
Role: _group_write
Delete multiple groups¶
New in version 4.8.
-
DELETE
/group
¶ Deletes the groups with the specified names.
Query Parameters: - name – Comma-separated list of group names. Must not be empty.
Role: _group_write
Example¶
DELETE /group?name=teachers,students,guests
Search groups¶
-
PUT
/group
¶ Simple search of fields
groupname
,description
and metadata.Query Parameters: - number – Return at most specified number of groups. Default is
10
. - role – Set to true to only return roles, false to only return 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
- number – Return at most specified number of groups. 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¶
Get parent groups to a group¶
-
GET
/group/
(group-name)/parents
¶ Returns groups that the specified group belongs to.
Query Parameters: - traverse –
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 –
Get child groups to a group¶
-
GET
/group/
(group-name)/children
¶ Returns groups that belongs to the specified group.
Query Parameters: - traverse –
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 –
Group-to-user relations¶
Users belonging to group¶
-
GET
/group/
(group-name)/users
¶ Returns all users belonging to the group/role, directly or indirectly.
Query Parameters: - traverse –
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 –