ownCloud
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage

Groups

Groups API

The Groups API is implementing a subset of the functionality of the MS Graph Group resource The JSON representation of a Group as handled by the Groups API looks like this:

{
    "displayName": "group",
    "id": "f0d97060-da16-4b0d-9fa4-d1ec43afc5f1"
}

Our implementation currently supports two Attributes for a Group:

Attribute Description
displayName The groups name
id An unique, stable readonly identifier for the group that stays the same for the whole lifetime of the User, usually a UUID

Reading groups

GET /groups

Returns a list of all groups

Example:

curl -k 'https://localhost:9200/graph/v1.0/groups' -u user:password

Response:

{
    "value": [
        {
            "displayName": "group",
            "id": "38580a2e-7018-42ed-aff6-b2af0b4e9790"
        },
        {
            "displayName": "Example Users",
            "id": "7a20f238-8a22-4458-902d-47674c317e5f"
        }
    ]
}

GET /groups/{groupid}

Example:

curl -k 'https://localhost:9200/graph/v1.0/groups/7a20f238-8a22-4458-902d-47674c317e5f' -u user:password

Response:

{
    "displayName": "Example Users",
    "id": "7a20f238-8a22-4458-902d-47674c317e5f"
}

Getting Group Members

GET /groups/{groupid}/members

Returns a list of User objects that are members of a group.

Example:

curl -k 'https://localhost:9200/graph/v1.0/groups/7a20f238-8a22-4458-902d-47674c317e5f/members' -u user:password

Response:

[
    {
        "displayName": "Test User",
        "id": "c54b0588-7157-4521-bb52-c1c8ca84ea71",
        "mail": "example@example.org",
        "onPremisesSamAccountName": "example"
    },
    {
        "displayName": "Albert Einstein",
        "id": "4c510ada-c86b-4815-8820-42cdf82c3d51",
        "mail": "einstein@example.org",
        "onPremisesSamAccountName": "einstein"
    }
]

Creating / Updating Groups

POST /groups

Use this to create a new group. h

Request Body

Note the missing "id" Attribute. It will be generated by the server:

{
    "displayName": "Example Users"
}
Response

When successful, the response will return the new group including the newly allocated "id":

{
    "displayName": "Example Users",
    "id": "7a20f238-8a22-4458-902d-47674c317e5f"
}

DELETE /groups/{id}

Example:

curl -k --request DELETE 'https://localhost:9200/graph/v1.0/groups/7a20f238-8a22-4458-902d-47674c317e5f' -u user:password

When successful the API returns no response body and the HTTP status code 204 (No Content)

PATCH /groups/{id}

Updating attributes of a single group is supposed to be done with a patch request. This is however currently not fully implemented for our write-enabled backends. The PATCH request can however be used to add multiple members to a group at once. See below.

Adding a single member to a group

POST /groups/{id}/members/$ref

The request body contains a single attribute “@odata.id” referencing the new member of the group by URI. Example:

curl -k --header "Content-Type: application/json" \
        --request POST  --data \
	'{ "@odata.id": "https://localhost:9200/graph/v1.0/users/4c510ada-c86b-4815-8820-42cdf82c3d51" }' \
	'https://localhost:9200/graph/v1.0/groups/7a20f238-8a22-4458-902d-47674c317e5f/members/$ref' -u user:password

When successful the API returns no response body and the HTTP status code 204 (No Content)

Adding multiple members in a single request

PATCH /groups/{id}

The request body contains the attribute members@odata.bind holding a list of URI references for the new members. Example:

{
    "members@odata.bind": [
        "https://localhost:9200/graph/v1.0/users/4c510ada-c86b-4815-8820-42cdf82c3d51",
	"https://localhost:9200/graph/v1.0/users/c54b0588-7157-4521-bb52-c1c8ca84ea71"
    ]
}

When successful the API returns no response body and the HTTP status code 204 (No Content)

Removing a member

DELETE /groups/{groupid}/members/{id}/$ref

Example

curl -k --request DELETE  \
     'https://localhost:9200/graph/v1.0/groups/7a20f238-8a22-4458-902d-47674c317e5f/members/4c510ada-c86b-4815-8820-42cdf82c3d51/$ref' \
     -u user:password

When successful the API returns no response body and the HTTP status code 204 (No Content)