DE EN EN (Google)

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:

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:

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