mirror of
https://github.com/opencloud-eu/opencloud.git
synced 2026-01-05 19:59:37 -06:00
docs: Add documenmtation for the graph users and group APIs
Addressed the Users and Groups Part of issue #3139
This commit is contained in:
Ralf Haferkamp
@@ -9,3 +9,5 @@ geekdocCollapseSection: true
|
||||
---
|
||||
|
||||
This service provides a simple graph world API which can be used by clients or other extensions.
|
||||
|
||||
{{< toc-tree >}}
|
||||
|
||||
199
docs/extensions/graph/groups.md
Normal file
199
docs/extensions/graph/groups.md
Normal file
@@ -0,0 +1,199 @@
|
||||
---
|
||||
title: Groups
|
||||
weight: 40
|
||||
geekdocRepo: https://github.com/owncloud/ocis
|
||||
geekdocEditPath: edit/master/docs/extensions/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 implemenation currently support 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 Reponse 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 to 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}/$ret`
|
||||
|
||||
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)
|
||||
165
docs/extensions/graph/users.md
Normal file
165
docs/extensions/graph/users.md
Normal file
@@ -0,0 +1,165 @@
|
||||
---
|
||||
title: Users
|
||||
weight: 30
|
||||
geekdocRepo: https://github.com/owncloud/ocis
|
||||
geekdocEditPath: edit/master/docs/extensions/graph
|
||||
geekdocFilePath: users.md
|
||||
---
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
## Users API
|
||||
|
||||
The Users API is implementing a subset of the functionality of the
|
||||
[MS Graph User resource](https://docs.microsoft.com/en-us/graph/api/resources/user?view=graph-rest-1.0)
|
||||
The JSON representation of a User handled by the Users API looks like this:
|
||||
|
||||
```
|
||||
{
|
||||
"displayName": "Albert Einstein",
|
||||
"id": "4c510ada-c86b-4815-8820-42cdf82c3d51",
|
||||
"mail": "einstein@example.org",
|
||||
"onPremisesSamAccountName": "einstein"
|
||||
}
|
||||
```
|
||||
|
||||
Our implemenation currently supports only a limited set of Attributes of Users:
|
||||
|
||||
| Attribute | Description |
|
||||
|---------------|-------------|
|
||||
| displayName | The full name of the user, usually a combination for givenname and lastname|
|
||||
| mail | The user's email address |
|
||||
| onPremisesSamAccountName | The loginname/account name of the user|
|
||||
| id | An unique, stable readonly identifier for the user that stays the same for the whole lifetime of the User, usually a UUID|
|
||||
| passwordProfile | Contains the password of the users. This is only present when updating or creating users. It is never returned by the API|
|
||||
|
||||
|
||||
### Reading users
|
||||
|
||||
#### `GET /me`
|
||||
|
||||
Returns the user object of the currently signed-in user
|
||||
|
||||
Example:
|
||||
```
|
||||
curl -k 'https://localhost:9200/graph/v1.0/me' -u user:password
|
||||
```
|
||||
|
||||
Response:
|
||||
```
|
||||
{
|
||||
"displayName": "Albert Einstein",
|
||||
"id": "4c510ada-c86b-4815-8820-42cdf82c3d51",
|
||||
"mail": "einstein@example.org",
|
||||
"onPremisesSamAccountName": "einstein"
|
||||
}
|
||||
```
|
||||
|
||||
#### `GET /users`
|
||||
|
||||
Returns a list of all users
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
curl -k 'https://localhost:9200/graph/v1.0/users' -u user:password
|
||||
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```
|
||||
{
|
||||
"value": [
|
||||
{
|
||||
"displayName": "Albert Einstein",
|
||||
"id": "4c510ada-c86b-4815-8820-42cdf82c3d51",
|
||||
"mail": "einstein@example.org",
|
||||
"onPremisesSamAccountName": "einstein"
|
||||
},
|
||||
{
|
||||
"displayName": "Maurice Moss",
|
||||
"id": "058bff95-6708-4fe5-91e4-9ea3d377588b",
|
||||
"mail": "moss@example.org",
|
||||
"onPremisesSamAccountName": "moss"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### `GET /users/{userid or accountname}`
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
curl -k 'https://localhost:9200/graph/v1.0/users/058bff95-6708-4fe5-91e4-9ea3d377588b' -u user:password
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```
|
||||
{
|
||||
"displayName": "Maurice Moss",
|
||||
"id": "058bff95-6708-4fe5-91e4-9ea3d377588b",
|
||||
"mail": "moss@example.org",
|
||||
"onPremisesSamAccountName": "moss"
|
||||
}
|
||||
```
|
||||
|
||||
### Creating / Updating Users
|
||||
|
||||
#### `POST /users`
|
||||
|
||||
Use this to create a new user.
|
||||
|
||||
##### Request Body
|
||||
|
||||
Note the missing `"id"` Attribute. It will be generated by the server:
|
||||
|
||||
```
|
||||
{
|
||||
"displayName": "Example User",
|
||||
"mail": "example@example.org",
|
||||
"onPremisesSamAccountName": "example",
|
||||
"passwordProfile": {
|
||||
"password": "ThePassword"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
##### Response
|
||||
|
||||
When successful, the Reponse will return the new user, without the password, but including the newly allocated `"id"`:
|
||||
|
||||
```
|
||||
{
|
||||
"displayName":"Example User",
|
||||
"id":"c067b139-c91c-4e47-8be6-669156a0587b",
|
||||
"mail":"example@example.org",
|
||||
"onPremisesSamAccountName":"example"
|
||||
}
|
||||
```
|
||||
|
||||
#### `DELETE /users/{id}`
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
curl -k --request DELETE 'https://localhost:9200/graph/v1.0/users/c067b139-c91c-4e47-8be6-669156a0587b' -u user:password
|
||||
```
|
||||
|
||||
When successful the API returns no Response Body and the HTTP status code 204 (No Content)
|
||||
|
||||
|
||||
#### `PATCH /users/{id}`
|
||||
|
||||
Updating attributes of a single user can be done with a patch request. The Request Body contains the new values of the attributes
|
||||
to be updated. E.g. to update the `displayName` Attribute:
|
||||
|
||||
```
|
||||
curl -k --header "Content-Type: application/json" \
|
||||
--request PATCH --data '{"displayName": "Test User" }' \
|
||||
'https://localhost:9200/graph/v1.0/users/c54b0588-7157-4521-bb52-c1c8ca84ea71' -u user:password
|
||||
```
|
||||
|
||||
Similar to creating a user via `POST`, the `PATCH` request will return the user object containing the new attribute values.
|
||||
Reference in New Issue
Block a user