TheDude
/
openproject
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
OpenProject is the leading open source project management software.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
59074 Commits
139 Branches
203 Tags
1.2 GiB
Tag: Branch: Tree: 700d9c5488
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '700d9c5488'
${ noResults }
openproject/docs/api/apiv3/endpoints/placeholder_users.apib

357 lines
14 KiB
Raw Normal View History Unescape

[36296] Add PlaceholderUsers API (#9033) * Add PlaceholderUsers API * Fix remarks in apib * Add deduce_element_decorator to collection * Remove unnecessary path
4 years ago
# Group Placeholder Users
## Actions
| Link | Description | Condition |
|:-------------------:| -------------------------------------------------------------------- | ---------------------------------------------------------------- |
| showUser | Link to the OpenProject placeholder user page (HTML) | |
| updateImmediately | Update a placeholder from the instance | **Permission**: manage_placeholder_user |
| delete | Permanently remove a placeholder from the instance | **Permission**: manage_placeholder_user |
## Linked Properties
| Link | Description | Type | Constraints | Supported operations | Condition |
|:-----------:|-------------------------------------------------------------- | ------------- | --------------------- | -------------------- | ----------------------------------------- |
| self | This user | User | not null | READ | |
| memberships | Link to collection of all the user's memberships. The list will only include the memberships in projects in which the requesting user has the necessary permissions. | MemberCollection | | READ | **Permission**: view members or manage members in any project |
## Local Properties
| Property | Description | Type | Constraints | Supported operations | Condition |
| :----------: | --------------------------------------------------------- | -------- | ---------------------------------------------------- | -------------------- | ----------------------------------------------------------- |
| id | Placeholder user's id | Integer | x > 0 | READ | |
| name | Placeholder user's full name, formatting depends on instance settings | String | | READ | |
| createdAt | Time of creation | DateTime | | READ | |
| updatedAt | Time of the most recent change to the user | DateTime | | READ | |
## PlaceholderUser [/api/v3/placeholder_users/{id}]
+ Model
+ Body
{
"_type": "PlaceholderUser",
"_links": {
"self": {
"href": "/api/v3/placeholder_users/1",
"title": "placeholder"
},
"show": {
"href": "/placeholder_users/1",
"type": 'text/html'
},
"delete": {
"href": "/api/v3/placeholder_users/1",
"method": "DELETE"
},
},
"id": 1,
"name": "placeholder",
"createdAt": "2014-05-21T08:51:20Z",
"updatedAt": "2014-05-21T08:51:20Z"
}
## View placeholder user [GET]
+ Parameters
+ id (required, integer)
+ Response 200 (application/hal+json)
[PlaceholderUser][]
+ Response 404 (application/hal+json)
Returned if the user does not exist or if the API user does not have permission to view them.
**Required permission** The user needs to have the manage_placeholder_user permission
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The specified user does not exist or you do not have permission to view them."
}
## Update placeholder user [PATCH]
Updates the placeholder user's writable attributes.
When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body.
+ Parameters
+ id (required, integer, `1`) ... Placeholder user id
+ Request Update PlaceholderUser (application/json)
+ Body
{
"name": "New name"
}
+ Response 200
[PlaceholderUser][]
+ Response 400 (application/hal+json)
Occurs when the client did not send a valid JSON object in the request body.
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request body was not a single JSON object."
}
+ Response 403 (application/hal+json)
Returned if the client does not have sufficient permissions.
**Required permission:** Administrators, manage_placeholder_user global permission
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not allowed to access this resource."
}
+ Response 404 (application/hal+json)
Returned if the user does not exist.
**Required permission:** Administrators, manage_placeholder_user global permission
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The requested resource could not be found."
}
+ Response 422 (application/hal+json)
Returned if:
* the client tries to modify a read-only property (`PropertyIsReadOnly`)
* a constraint for a property was violated (`PropertyConstraintViolation`)
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
"message": "Name is already taken.",
"_embedded": {
"details": {
"attribute": "name"
}
}
}
## Delete placeholder user [DELETE]
Permanently deletes the specified placeholder. This action will be performed asynchronously
and the response will only accept the deletion request. The actual deletion will then potentially take a while.
+ Parameters
+ id (required, integer, `1`) ... Placeholder user id
+ Response 202
Returned if the account was successfully scheduled for deletion.
+ Body
+ Response 403 (application/hal+json)
Returned if the client does not have sufficient permissions.
**Required permission:** Administrators or manage_placeholder_user permission
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource"
}
+ Response 404 (application/hal+json)
Returned if the user does not exist.
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The requested resource could not be found."
}
## PlaceholderUsers [/api/v3/users{?offset,pageSize,filters,sortBy}]
+ Model
+ Body
{
"_links": {
"self": { "href": "/api/v3/placeholder_users" }
},
"total": 2,
"count": 1,
"_type": "Collection",
"_embedded": {
"elements": [
{
"_type": "PlaceholderUser",
"_links": {
"self": {
"href": "/api/v3/placeholder_users/1",
"title": "placeholder"
},
"showUser": {
"href": "/placeholder_users/1",
"type": 'text/html'
},
"updateImmediately": {
"href": "/api/v3/placeholder_users/1",
"title": "Update placeholder"
"method": "PATCH"
},
"delete": {
"href": "/api/v3/placeholder_users/1",
"title": "Delete placeholder"
"method": "DELETE"
}
},
"id": 1,
"name": "placeholder",
"createdAt": "2014-05-21T08:51:20Z",
"updatedAt": "2014-05-21T08:51:20Z"
}
]
}
}
## List Placeholder Users [GET]
Lists placeholders. Only administrators or users with manage_placeholder_user global permission have permission to do this.
+ Parameters
+ offset = `1` (optional, integer, `25`) ... Page number inside the requested collection.
+ pageSize (optional, integer, `25`) ... Number of elements to display per page.
+ filters (optional, string, `[{ "group": { "operator": "=", "values": ["1"] } }, { "name": { "operator": "=", "values": ["placeholder"] } }]`) ... JSON specifying filter conditions.
Accepts the same format as returned by the [queries](#queries) endpoint. Currently supported filters are:
+ group: Name of the group in which to-be-listed placeholder users are members.
+ name: Filter placeholder users in whose first or last names, or email addresses the given string occurs.
+ status: Filter placeholder users by their status. Possible values are "active" and "locked"
+ sortBy (optional, string, `[["name", "asc"]]`) ... JSON specifying sort criteria.
Accepts the same format as returned by the [queries](#queries) endpoint.
Currently supported orders are:
+ id
+ name
+ group
+ Response 200 (application/hal+json)
[PlaceholderUsers][]
+ Response 400 (application/hal+json)
Returned if the client sends an unknown sort column.
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidQuery",
"message": "Unknown sort column."
}
+ Response 403 (application/hal+json)
Returned if the client does not have sufficient permissions.
**Required permission:** Administrator or manage_placeholder_user permission
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
## Create placeholder user [/api/v3/placeholder_users]
## Create Placeholder User [POST]
Creates a new placeholder user. Only administrators and users with manage_placeholder_user global permission are allowed to do so.
When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body.
+ Request Create User (application/json)
+ Body
{
"name": "placeholder"
}
+ Response 201
[PlaceholderUser][]
+ Response 400 (application/hal+json)
Occurs when the client did not send a valid JSON object in the request body.
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request body was not a single JSON object."
}
+ Response 403 (application/hal+json)
Returned if the client does not have sufficient permissions.
**Required permission:** Administrator or manage_placeholder_user
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
+ Response 422 (application/hal+json)
Returned if:
* a constraint for a property was violated (`PropertyConstraintViolation`)
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
"message": "Name is already taken.",
"_embedded": {
"details": {
"attribute": "name"
}
}
}