From 5f6bb591b21bc4a5d50c2c6dca832eedf80b2039 Mon Sep 17 00:00:00 2001 From: Ralf Haferkamp Date: Thu, 10 Feb 2022 15:01:35 +0100 Subject: [PATCH] docs: Add documenmtation for the graph users and group APIs Addressed the Users and Groups Part of issue #3139 --- docs/extensions/graph/_index.md | 2 + docs/extensions/graph/groups.md | 199 ++++++++++++++++++++++++++++++++ docs/extensions/graph/users.md | 165 ++++++++++++++++++++++++++ 3 files changed, 366 insertions(+) create mode 100644 docs/extensions/graph/groups.md create mode 100644 docs/extensions/graph/users.md diff --git a/docs/extensions/graph/_index.md b/docs/extensions/graph/_index.md index 3ad1e8d9b81..7ff7bc687c4 100644 --- a/docs/extensions/graph/_index.md +++ b/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 >}} diff --git a/docs/extensions/graph/groups.md b/docs/extensions/graph/groups.md new file mode 100644 index 00000000000..56c92fa19d9 --- /dev/null +++ b/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": "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) diff --git a/docs/extensions/graph/users.md b/docs/extensions/graph/users.md new file mode 100644 index 00000000000..2a20d23a61b --- /dev/null +++ b/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": "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.