-
Notifications
You must be signed in to change notification settings - Fork 187
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[docs-only] Add documemtation for the graph users and group APIs #3149
Merged
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
@@ -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. | ||||||
rhafer marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
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` | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. typo?
Suggested change
|
||||||
|
||||||
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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Response Body
should always be lower case as it is not pointing to a resource