docs: Add documenmtation for the graph users and group APIs

Addressed the Users and Groups Part of issue #3139

docs/extensions/graph/_index.md

@@ -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 >}}

docs/extensions/graph/groups.md

@@ -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": "[email protected]",
+        "onPremisesSamAccountName": "example"
+    },
+    {
+        "displayName": "Albert Einstein",
+        "id": "4c510ada-c86b-4815-8820-42cdf82c3d51",
+        "mail": "[email protected]",
+        "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 `[email protected]` holding a list of URI references for the new members.
+Example:
+
+```
+{
+    "[email protected]": [
+        "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)

docs/extensions/graph/users.md

@@ -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": "[email protected]",
+    "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": "[email protected]",
+    "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": "[email protected]",
+            "onPremisesSamAccountName": "einstein"
+        },
+        {
+            "displayName": "Maurice Moss",
+            "id": "058bff95-6708-4fe5-91e4-9ea3d377588b",
+            "mail": "[email protected]",
+            "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": "[email protected]",
+    "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": "[email protected]",
+    "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":"[email protected]",
+    "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.