Retrieve groups

GET /api/v1/group[/<id>]?token=<token>[&limit=<limit>][&offset=<offset>][&type=<type>]

Retrieves one or a list of groups, ordered by the group ID (ascending).

Path parameters


`id`	Object ID (integer, optional): if set, get group `id`

Query String


`token`	Session token acquired with /api/v1/session
`limit`	Return no more than `<limit>` groups. Default: `1000`, maximum: `1000`
`offset`	Skip first `<offset>` groups. Default: `0`
`type`	Return groups belonging to at least one of the types (comma seperated list). Example: `system,easydb,...`

Returns

Array of groups.

If id was specified and no group was found, this call returns an empty array.

Permissions

The session must be authenticated and the user requires the system.group right.

The following groups can be read by a user:

“easydb” groups the user belongs to
groups for which the user has the bag_read right

HTTP status codes


200	Success
400	API error: something is malformed
400	Not Authenticated: session is not authenticated
400	No System Right: no `system.group` right
400	Insufficient Rights: no `bag_read` right
400	Group Not Found: group `id` not found
500	Server error: internal server error

Examples

Request:  GET /api/v1/group

Response: HTTP 200
[
    {
        "_basetype": "group",
        "group": {
            "_id": 1,
            "_version": 1,
            "is_system_group": true,
            "name": ":all",
            "displayname": {
                "de-DE": "Alle Benutzer",
                "en-US": "all users"
            }
        }
    },
    {
        "_basetype": "group",
        "group": {
            "_id": 2,
            "_version": 3,
            "is_system_group": false,
            "name": "dept_head",
            "displayname": {
                "de-DE": "Abteilungsleiter",
                "en-US": "Department Heads"
            }
        }
    }
]

Request:  GET /api/v1/group/2

Response: HTTP 200
[
    {
        "_basetype": "group",
        "group": {
            "_id": 2,
            "_version": 3,
            "is_system_group": false,
            "name": "dept_head",
            "displayname": {
                "de-DE": "Abteilungsleiter",
                "en-US": "Department Heads"
            }
        }
    }
]

Insert or update groups

POST/PUT /api/v1/group?token=<token>

Creates (PUT) or updates (POST) groups.

Query String


`token`	Session token acquired with /api/v1/session

Input

Array of groups.

Ouput

Array of groups that were updated.

Permissions

The session must be authenticated.

Updating a group

The user must have the bag_write right for the group.

Creating a group

If a group is created, the user requires the system.group right with create.

When creating a group, the owner will be set to the session user. An attempt to set a different owner will trigger a Change Owner On Creation error.

HTTP status codes


200	Success
400	API error: something is malformed
400	Not Authenticated: session is not authenticated
400	Insufficient Rights: no “bag_write” right
400	No System Right: user lacks the required system right to update the group
400	Change Owner On Creation: the user attempted to set a different owner than him-/herself when creating a user
400	Group Not Found: group not found (`group._id`, or in `_acl.who` or `_owner.who`)
400	User Not Found: user not found (in `_acl.who` or `_owner.who)
400	Right Not Found: a right that was provided for `_acl` or `_system_rights` was not found
400	Custom Type Required: attempting to assign the “system.user.create_new” right with type “custom” but without specifying the “custom_type”
500	Server error: internal server error

Examples

Request:  PUT /api/v1/group
[
    {
        "_basetype": "group",
        "group": {
            "_version": 1,             // Version is 1. No ID is given
            "name": "students",
            "displayname": {
                "de-DE": "Studenten",
                "en-US": "Students"
            }
        }
    }
]

Response: HTTP 200
[
    {
        "_basetype": "group",
        "group": {
            "_id": 54,                  // ID is returned in the response
            "_version": 1,
            "name": "students",
            "displayname": {
                "de-DE": "Studenten",
                "en-US": "Students"
            }
        }
    }
]

Request:  POST /api/v1/group
[
    {
        "_basetype": "group",
        "group": {
            "id": 2,               // ID must be given
            "_version": 4,         // Old version was 3, next version (4) is provided
            "name": "dept_head",
            "displayname": {
                "de-DE": "Abteilungsleitergruppe",
                "en-US": "Group of Department Heads"
            }
        }
    }
]

Response: HTTP 200
[
    {
        "_basetype": "group",
        "group": {
            "id": 2,
            "_version": 4,
            "name": "dept_head",
            "displayname": {
                "de-DE": "Abteilungsleitergruppe",
                "en-US": "Group of Department Heads"
            }
        }
    }
]

Delete group

DELETE /api/v1/group/<id>?token=<token>

Delete a group.

Path parameters


`id`	Group ID (integer)

Query String


`token`	Session token acquired with /api/v1/session

Examples

Request:  DELETE /api/v1/group/2
Response: HTTP 200

Permissions

The session must be authenticated and:

the user must have the bag_delete right for the group provided

System groups are not allowed to be deleted.

HTTP status codes


200	Success
400	API error: something is malformed
400	Not Authenticated: session is not authenticated
400	Group Not Found: group `id` not found
400	Insufficient Rights: no “bag_delete” right
500	Server error: internal server error