docs: Add documenmtation for the graph users and group APIs

Addressed the Users and Groups Part of issue #3139
2022-02-14 12:19:52 +01:00
parent 21c7b10f98
commit 5f6bb591b2
3 changed files with 366 additions and 0 deletions
@@ -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)