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

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:
Role:

_group_write

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:
Produces:
  • application/xml, application/json – GroupListDocument
  • text/plain – CRLF-delimited list of group names

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

Retrieve the group description

GET /group/(group-name)/description

Returns the descriptive text about the specified group.

Produces:
  • text/plain – Group description
Role:

_group_read

Update the description of a group

PUT /group/(group-name)/description

Changes the description of a group.

Accepts:
  • text/plain – The new description.
Role:

_group_write

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

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

Add a group to another group

PUT /group/(group-name)/group/(child-groupname)

Creates parent-child relation between the two specified groups.

Role:_group_write

Remove a group from another group

DELETE /group/(group-name)/group/(child-groupname)

Removes the parent-child relation between the two specified groups.

Role:_group_write

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:
Role:

_group_read

Add a user to a group

PUT /group/(group-name)/user/(username)

Adds the specified user to the specified group.

Role:_group_write

Remove a user from a group

DELETE /group/(group-name)/user/(username)

Removes the specified user from the specified group.

Role:_group_write