---
title: Groups
weight: 40
geekdocRepo: https://github.com/owncloud/ocis
geekdocEditPath: edit/master/docs/services/graph
geekdocFilePath: users.md
---

{{< toc >}}

## Groups API

The Groups API is implementing a subset of the functionality of the
[MS Graph Group resource](https://docs.microsoft.com/en-us/graph/api/resources/group?view=graph-rest-1.0)
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)