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 Group, 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?$expand=members`

Returns a list of all groups including its members

Example:

curl -k 'https://localhost:9200/graph/v1.0/groups?$expand=members' -u user:password

Response:

{
    "value": [
        {
            "displayName": "group",
            "id": "38580a2e-7018-42ed-aff6-b2af0b4e9790",
            "members": [
                {
                    "displayName": "user1",
                    "id": "2e7b7e23-6c42-4d34-81b0-2bed34e51983",
                    "mail": "user1@example.org",
                    "onPremisesSamAccountName": "user1"
                },
                {
                    "displayName": "user2",
                    "id": "b45c9e35-0d95-4165-96bc-68bff4a316ed",
                    "mail": "user2@example.org",
                    "onPremisesSamAccountName": "user2"
                }
            ]
        },
        {
            "displayName": "Example Users",
            "id": "7a20f238-8a22-4458-902d-47674c317e5f",
            "members": [
                {
                    "displayName": "user3",
                    "id": "026fbfef-79ef-4f5d-887b-9eaf42777239",
                    "mail": "user3@example.org",
                    "onPremisesSamAccountName": "user3"
                }
            ]
        }
    ]
}

`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"
}

`GET /groups/{groupid}?$expand=members`

Example:

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

Response:

{
    "displayName": "Example Users",
    "id": "7a20f238-8a22-4458-902d-47674c317e5f",
    "members": [
        {
            "displayName": "user3",
            "id": "026fbfef-79ef-4f5d-887b-9eaf42777239",
            "mail": "user3@example.org",
            "onPremisesSamAccountName": "user3"
        }
    ]
}

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)