Web API for User Management: Difference between revisions
Jump to navigation
Jump to search
No edit summary |
|||
| Line 1: | Line 1: | ||
This page describes | This page describes Web API operations for managing users, groups, roles and permissions. | ||
== Entities == | == Entities == | ||
The user management API | The user management API uses the following entities. | ||
===User/group=== | ===User/group=== | ||
The '''User/group''' entity | The '''User/group''' entity includes both users and groups. Properties: | ||
* Id (integer): user/group id. | * Id (integer): user/group id. | ||
* IsGroup (boolean): ''false'' for users, ''true'' for groups. | * IsGroup (boolean): ''false'' for users, ''true'' for groups. | ||
* LoginName (string): user login name | * LoginName (string): user login name. Empty/ignored for groups. | ||
* FullName (string): user/group full name. | * FullName (string): user/group full name. | ||
* Email (string): user/group email address. | * Email (string): user/group email address. | ||
| Line 16: | Line 16: | ||
===Role assignment=== | ===Role assignment=== | ||
The '''Role assignment''' describes that a role is given to a certain user/group. Properties: | The '''Role assignment''' entity describes that a role is given to a certain user/group. Properties: | ||
* Id (integer): user/group id | * Id (integer): user/group id | ||
* ProjectId (integer): project id | * ProjectId (integer): project id used in project-specific role assignments. Not used for global permissions. | ||
* RoleId (integer): role id | * RoleId (integer): role id | ||
===Membership=== | ===Membership=== | ||
The '''Membership''' describes that a user belongs to a group. Properties: | The '''Membership''' entity describes that a user belongs to a group. Properties: | ||
* GroupId (integer): parent (container) group id. | * GroupId (integer): parent (container) group id. | ||
* MemberId (integer): child (member) user/group id. | * MemberId (integer): child (member) user/group id. | ||
* RoleName (string): membership | * RoleName (string): Type of the membership. Supported types are '''Member''', '''HiddenMember''', '''Administrator'''. | ||
===Role=== | ===Role=== | ||
The '''Roles''' | The '''Roles''' describes roles in the system. Properties: | ||
* Id (integer): role id. | * Id (integer): role id. | ||
* Name (string): role name. | * Name (string): role name. | ||
* IsGlobal (boolean): ''true'' | * IsGlobal (boolean): ''true'' for global role, ''false'' for project-specific-only role. Note that a role can be both global and user-specific. | ||
* IsProject (boolean): ''true'' | * IsProject (boolean): ''true'' for project-specific role, ''false'' for global-only role. Note that a role can be both global and user-specific. | ||
==Methods== | ==Methods== | ||
| Line 39: | Line 39: | ||
GET api/users | GET api/users | ||
</pre> | </pre> | ||
Gets a list of users/ | Gets a list of ''users/group'' entities. Can be an empty array if criteria specified by parameters is not matched. Supported query parameters: | ||
* ''isGroup'' (boolean): if false, only users are returned; if true, only groups are returned. | * ''isGroup'' (boolean): if ''false'', only users are returned; if true, only groups are returned. If omitted, both users and groups are returned. | ||
* ''isActive'' (boolean): if false or omitted, all users/groups are returned; if true, only active users/groups are returned | * ''isActive'' (boolean): if ''false'' or omitted, all users/groups are returned; if ''true'', only active users/groups are returned. | ||
<pre> | <pre> | ||
GET api/users/{id} | GET api/users/{id} | ||
</pre> | </pre> | ||
Gets information of the user/group with given id. Returns the user/group object. Can return null if not found. | Gets information of the ''user/group'' with given ''id''. Returns the user/group object. Can return null if a user/group is not found. | ||
<pre> | <pre> | ||
POST api/users | POST api/users | ||
</pre> | </pre> | ||
Creates a new user/group. Takes a user/group object in the body. Note that the ''id'' property is ignored if specified. Returns id of the created user/group. | Creates a new ''user/group''. Takes a user/group object in the body. Note that the ''id'' property is ignored if specified. Returns the id of the created user/group. | ||
<pre> | <pre> | ||
PUT api/users | PUT api/users | ||
</pre> | </pre> | ||
Updates an existing user/group. Takes a user/group object in the body. Note that the ''isGroup'' property is ignored. | Updates an existing ''user/group''. Takes a user/group object in the body. Note that the ''isGroup'' property is ignored, because users cannot be changed to groups and vice versa. | ||
<pre> | <pre> | ||
GET api/users/roleassignments/{id} | GET api/users/roleassignments/{id} | ||
</pre> | </pre> | ||
Gets a list of role assignments of | Gets a list of ''role assignments'' of a user/group with the given id. Returns an array of role assignment objects. | ||
<pre> | <pre> | ||
PUT api/users/roleassignments | PUT api/users/roleassignments | ||
</pre> | </pre> | ||
Adds a role assignment. Takes a role assignment object in the body. | Adds a ''role assignment''. Takes a role assignment object in the body. | ||
<pre> | <pre> | ||
DELETE api/users/roleassignments | DELETE api/users/roleassignments | ||
</pre> | </pre> | ||
Deletes a ''role assignment''. Takes a role assignment object in the body. | |||
<pre> | <pre> | ||
GET api/users/memberships/{id} | GET api/users/memberships/{id} | ||
</pre> | </pre> | ||
Gets a list of memberships of the user/group with given id. Returns an array of membership objects, which can be empty if user/group is not member of any group. | Gets a list of ''memberships'' of the user/group with given id. Returns an array of membership objects, which can be empty if user/group is not a member of any group. | ||
<pre> | <pre> | ||
PUT api/users/memberships | PUT api/users/memberships | ||
</pre> | </pre> | ||
Adds a membership. Takes a membership object in the body. | Adds a ''membership''. Takes a membership object in the body. | ||
<pre> | <pre> | ||
DELETE api/users/memberships | DELETE api/users/memberships | ||
</pre> | </pre> | ||
Deletes a ''membership''. Takes a membership object in the body. | |||
<pre> | <pre> | ||
GET api/users/roles | GET api/users/roles | ||
</pre> | </pre> | ||
Gets a list of all roles in the system. Returns an array of role objects. | Gets a list of all roles in the system. Returns an array of ''role'' objects. | ||
Revision as of 17:34, 13 August 2020
This page describes Web API operations for managing users, groups, roles and permissions.
Entities
The user management API uses the following entities.
User/group
The User/group entity includes both users and groups. Properties:
- Id (integer): user/group id.
- IsGroup (boolean): false for users, true for groups.
- LoginName (string): user login name. Empty/ignored for groups.
- FullName (string): user/group full name.
- Email (string): user/group email address.
- Password (string): user password. Used only when creating or updating users.
- IsActive (boolean): flag whether user/group is active.
- Description (string): user/group description.
Role assignment
The Role assignment entity describes that a role is given to a certain user/group. Properties:
- Id (integer): user/group id
- ProjectId (integer): project id used in project-specific role assignments. Not used for global permissions.
- RoleId (integer): role id
Membership
The Membership entity describes that a user belongs to a group. Properties:
- GroupId (integer): parent (container) group id.
- MemberId (integer): child (member) user/group id.
- RoleName (string): Type of the membership. Supported types are Member, HiddenMember, Administrator.
Role
The Roles describes roles in the system. Properties:
- Id (integer): role id.
- Name (string): role name.
- IsGlobal (boolean): true for global role, false for project-specific-only role. Note that a role can be both global and user-specific.
- IsProject (boolean): true for project-specific role, false for global-only role. Note that a role can be both global and user-specific.
Methods
GET api/users
Gets a list of users/group entities. Can be an empty array if criteria specified by parameters is not matched. Supported query parameters:
- isGroup (boolean): if false, only users are returned; if true, only groups are returned. If omitted, both users and groups are returned.
- isActive (boolean): if false or omitted, all users/groups are returned; if true, only active users/groups are returned.
GET api/users/{id}
Gets information of the user/group with given id. Returns the user/group object. Can return null if a user/group is not found.
POST api/users
Creates a new user/group. Takes a user/group object in the body. Note that the id property is ignored if specified. Returns the id of the created user/group.
PUT api/users
Updates an existing user/group. Takes a user/group object in the body. Note that the isGroup property is ignored, because users cannot be changed to groups and vice versa.
GET api/users/roleassignments/{id}
Gets a list of role assignments of a user/group with the given id. Returns an array of role assignment objects.
PUT api/users/roleassignments
Adds a role assignment. Takes a role assignment object in the body.
DELETE api/users/roleassignments
Deletes a role assignment. Takes a role assignment object in the body.
GET api/users/memberships/{id}
Gets a list of memberships of the user/group with given id. Returns an array of membership objects, which can be empty if user/group is not a member of any group.
PUT api/users/memberships
Adds a membership. Takes a membership object in the body.
DELETE api/users/memberships
Deletes a membership. Takes a membership object in the body.
GET api/users/roles
Gets a list of all roles in the system. Returns an array of role objects.