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.

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)