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.
29492 Commits
139 Branches
203 Tags
1.2 GiB
Tag: Branch: Tree: 6cbfc7ffed
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '6cbfc7ffed'
${ noResults }
openproject/doc/apiv3/endpoints/users.apib

971 lines
36 KiB
Raw Normal View History Unescape

Extract APIV3 documentation into single endpoints This does not differentiate further inside an endpoint and while useful (for e.g., work packages) we should discuss how the structure inside an endpoint should look like.
8 years ago
# Group Users
## Actions
| Link | Description | Condition |
|:-------------------:| -------------------------------------------------------------------- | ---------------------------------------------------------------- |
| lock | Restrict the user from logging in and performing any actions | not locked; **Permission**: Administrator |
| show | Link to the OpenProject user page (HTML) | |
| unlock | Allow a locked user to login and act again | locked; **Permission**: Administrator |
| update | Updates the user's attributes. | **Permission**: Administrator unless the API user updates itself |
| updateImmediately | Updates the user's attributes. | **Permission**: Administrator unless the API user updates itself |
| delete | Permanently remove a user from the instance | **Permission**: Administrator, self-delete |
## Linked Properties
| Link | Description | Type | Constraints | Supported operations |
|:---------:|-------------------------------------------- | ------------- | --------------------- | -------------------- |
| self | This user | User | not null | READ |
| schema | Schema describing the user | Schema | not null | READ |
## Local Properties
| Property | Description | Type | Constraints | Supported operations | Condition |
| :---------: | --------------------------------------------------------- | -------- | ---------------------------------------------------- | -------------------- | ----------------------------------------------------------- |
| id | User's id | Integer | x > 0 | READ | |
| login | User's login name | String | unique, 256 max length | READ / WRITE | **Permission**: Administrator unless user updates itself |
| firstName | User's first name | String | 30 max length | READ / WRITE | **Permission**: Administrator unless user updates itself |
| lastName | User's last name | String | 30 max length | READ / WRITE | **Permission**: Administrator unless user updates itself |
| name | User's full name, formatting depends on instance settings | String | | READ | |
| email | User's E-Mail address | String | unique, 60 max length | READ / WRITE | E-Mail address not hidden, **Permission**: Administrator unless user updates itself |
| admin | Flag indicating whether or not the user is an admin | Boolean | in: [true, false] | READ / WRITE | **Permission**: Administrator |
| avatar | URL to user's avatar | Url | | READ | |
| status | The current activation status of the user (see below) | String | in: ["active", "registered", "locked", "invited"] | READ | |
| language | User's language | String | ISO 639-1 | READ / WRITE | **Permission**: Administrator unless user updates itself |
| password | User's password | String | | WRITE | **Permission**: Administrator unless user updates itself |
| createdAt | Time of creation | DateTime | | READ | |
| updatedAt | Time of the most recent change to the user | DateTime | | READ | |
The `status` of a user can be one of:
* `active` - the user can log in with the account
* `registered` - the user just registered to the instance, he can't log in yet, but will be able to, once the registration is completed
* `locked` - the user is locked and can't log in
* `invited` - the user has been invited and is pending registration
The `language` is limited to those activated in the system.
Due to data privacy, the user's properties are limited to reveal as little about the user as possible. Thus `login`, `firstName`, `lastName`, `language`, `createdAt` and `updatedAt` are hidden for all users except for admins or the user themselves.
Please note that custom fields are not yet supported by the api although the backend supports them.
## User [/api/v3/users/{id}]
+ Model
+ Body
{
"_type": "User",
"_links": {
"self": {
"href": "/api/v3/users/1",
"title": "j.sheppard"
},
"show": {
"href": "/users/1",
"type": 'text/html'
},
"lock": {
"href": "/api/v3/users/1/lock",
"method": "POST"
},
"update": {
"href": "/api/v3/users/1/form",
"method": "POST"
},
"updateImmediately": {
"href": "/api/v3/users/1",
"method": "PATCH"
},
"delete": {
"href": "/api/v3/users/1",
"method": "DELETE"
},
"schema": {
"href": "/api/v3/users/schema",
}
},
"id": 1,
"login": "j.sheppard",
"firstName": "John",
"lastName": "Sheppard",
"email": "shep@mail.com",
"admin": true,
"avatar": "https://gravatar/avatar",
"status": "active",
"language": "en",
"createdAt": "2014-05-21T08:51:20Z",
"updatedAt": "2014-05-21T08:51:20Z"
}
## View user [GET]
+ Parameters
+ id (required, integer, `1`) ... User id
+ Response 200 (application/hal+json)
[User][]
+ 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 be locked in if the installation is configured to pervent anonymous access
+ 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 user [PATCH]
Updates the 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`) ... User id
+ Request Update User (application/json)
+ Body
{
"login": "h.wurst",
"email": "h.wurst@openproject.com",
"firstName": "Hans",
"lastName": "Wurst",
"admin": true,
"language": "en"
}
+ Response 200
[User][]
+ 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 only (exception: users may update their own accounts)
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not allowed to update the account of this user."
}
+ Response 404 (application/hal+json)
Returned if the user does not exist or if the API user does not have the necessary permissions to update it.
**Required permission:** Administrators only (exception: users may update their own accounts)
+ 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."
}
+ 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": "The email address is already taken.",
"_embedded": {
"details": {
"attribute": "email"
}
}
}
## Delete user [DELETE]
Permanently deletes the specified user account.
+ Parameters
+ id (required, integer, `1`) ... User id
+ Response 202
Returned if the account was deleted successfully.
Note that the response body is empty as of now. In future versions of the API a body
*might* be returned, indicating the progress of deletion.
+ Body
+ Response 403 (application/hal+json)
Returned if the client does not have sufficient permissions or if deletion of users was disabled in the instance wide settings.
**Required permission:** Administrators only (exception: users might be able to delete their own accounts)
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not allowed to delete the account of this user."
}
+ 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 specified user does not exist."
}
## User Account Locking [/api/v3/users/{id}/lock]
## Set Lock [POST]
+ Parameters
+ id (required, integer, `1`) ... User id
+ Response 200 (application/hal+json)
[User][]
+ Response 400 (application/hal+json)
Returned if the client tries to lock a user account whose current status does not allow this transition.
**Required permission:** Administrators only
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidUserStatusTransition",
"message": "The current user account status does not allow this operation."
}
+ Response 403 (application/hal+json)
Returned if the client does not have sufficient permissions for locking a user.
**Required permission:** Administrators only
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not allowed to lock the account of this user."
}
+ 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 specified user does not exist."
}
## Remove Lock [DELETE]
+ Parameters
+ id (required, integer, `1`) ... User id
+ Response 200 (application/hal+json)
[User][]
+ Response 400 (application/hal+json)
Returned if the client tries to unlock a user account whose current status does not allow this transition.
**Required permission:** Administrators only
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidUserStatusTransition",
"message": "The current user account status does not allow this operation."
}
+ Response 403 (application/hal+json)
Returned if the client does not have sufficient permissions for unlocking a user.
**Required permission:** Administrators only
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not allowed to unlock the account of this user."
}
+ 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 specified user does not exist."
}
## User Schema [/api/v3/users/schema]
## View User Schema [GET]
+ Response 200 (application/hal+json)
+ Body
{
"_type": "Schema",
"_links": {
"self": { "href": "/api/v3/users/schema" }
},
"id": {
"name": "Id",
"type": "Integer",
"writable": false
},
"login": {
"name": "Login",
"type": "String",
"writable": true,
"required" true,
"minLength": 1,
"maxlength": 256
},
"firstName": {
"name": "First name",
"type": "String",
"writable": true,
"required" true,
"minLength": 1,
"maxLength": 30
},
"lastName": {
"name": "Last name",
"type": "String",
"writable": true,
"required" true,
"minLength": 1,
"maxLength": 30
},
"name": {
"name": "Name",
"type": "String",
"writable": false
},
"email": {
"name": "Email",
"type": "String",
"writable": true,
"required" true,
"minLength": 1,
"maxLength": 60
},
"admin": {
"name": "Administrator",
"type": "Boolean",
"writable": true,
},
"avatar": {
"name": "Avatar",
"type": "Url",
"writable": false,
},
"status": {
"name": "Status",
"type": "String",
"writable": false
}
"language": {
"name": "Language",
"type": "String",
"writable": true
},
"password": {
"name": "Password",
"type": "String",
"writable": true
},
"createdAt": {
"name": "Created at",
"type": "DateTime",
"writable": false
},
"updatedAt": {
"name": "Updated at",
"type": "DateTime",
"writable": false
}
}
+ Response 403 (application/hal+json)
Returned if the user lacks permissions to view the schema.
**Required permission** The user needs to be locked in if the installation is configured to pervent anonymous access
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not allowed to view the user schema."
}
## User Edit Form [/api/v3/users/{id}/form]
This endpoint returns a form to allow a guided modification of an existing user.
For more details and all possible responses see the general specification of [Forms](#forms).
## User Edit Form [POST]
+ Parameters
+ id (required, integer, `1`) ... ID of the user being modified
+ Response 200 (application/hal+json)
+ Body
{
"_links": {
"self": { "href": "/api/v3/users/form" },
"validate": {
"href": "/api/v3/users/form",
"method": "POST"
},
"commit": {
"href": "/api/v3/users",
"method": "POST"
}
},
"_type": "Form",
"_embedded": {
"payload": {
"login": "h.wurst",
"email": "h.wurst@openproject.com",
"firstName": "Hans",
"lastName": "Wurst",
"admin": false,
"language": "de",
"status": "active",
"password": "hunter5"
},
"schema": {
"_type": "Schema",
"id": {
"name": "Id",
"type": "Integer",
"writable": false
},
"login": {
"name": "Login",
"type": "String",
"writable": true,
"required" true,
"minLength": 1,
"maxlength": 256
},
"firstName": {
"name": "First name",
"type": "String",
"writable": true,
"required" true,
"minLength": 1,
"maxLength": 30
},
"lastName": {
"name": "Last name",
"type": "String",
"writable": true,
"required" true,
"minLength": 1,
"maxLength": 30
},
"name": {
"name": "Name",
"type": "String",
"writable": false
},
"email": {
"name": "Email",
"type": "String",
"writable": true,
"required" true,
"minLength": 1,
"maxLength": 60
},
"admin": {
"name": "Administrator",
"type": "Boolean",
"writable": true,
},
"avatar": {
"name": "Avatar",
"type": "Url",
"writable": false,
},
"status": {
"name": "Status",
"type": "String",
"writable": false
}
"language": {
"name": "Language",
"type": "String",
"writable": true,
"allowedValues": [
"en",
"fr",
"de"
]
},
"password": {
"name": "Password",
"type": "String",
"writable": true
},
"createdAt": {
"name": "Created at",
"type": "DateTime",
"writable": false
},
"updatedAt": {
"name": "Updated at",
"type": "DateTime",
"writable": false
},
"customField5" {
"name": "Retired",
"type": "Boolean",
"writable": true
}
}
"validationErrors": {
"subject": {
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:BadExampleError",
"message": "For the purpose of this example we need a validation error. The remainder of the response pretends there were no errors."
}
}
}
}
+ Response 403 (application/hal+json)
Returned if the client does not have sufficient permissions.
**Required permission:** Administrator or logged in user editing her/himself
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not allowed to edit the specified user."
}
+ Response 404 (application/hal+json)
Returned if the user does not exist or the client does not have sufficient permissions to see it.
**Required permission** The user needs to be locked in if the installation is configured to pervent anonymous access
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The specified user does not exist."
}
## Users [/api/v3/users{?offset,pageSize,filters,sortBy}]
+ Model
+ Body
{
"_links": {
"self": { "href": "/api/v3/users" }
},
"total": 2,
"count": 1,
"_type": "Collection",
"_embedded": {
"elements": [
{
"_type": "User",
"_links": {
"self": {
"href": "/api/v3/users/1",
"title": "John Sheppard - j.sheppard"
},
"showUser": {
"href": "/users/1",
"type": 'text/html'
},
"lock": {
"href": "/api/v3/users/1/lock",
"title": "Set lock on j.sheppard"
"method": "POST"
},
"update": {
"href": "/api/v3/users/1",
"title": "Update j.sheppard"
"method": "PATCH"
},
"delete": {
"href": "/api/v3/users/1",
"title": "Delete j.sheppard"
"method": "DELETE"
}
},
"id": 1,
"login": "j.sheppard",
"firstName": "John",
"lastName": "Sheppard",
"email": "shep@mail.com",
"admin": true,
"avatar": "https://gravatar/avatar",
"status": "active",
"language": "en",
"createdAt": "2014-05-21T08:51:20Z",
"updatedAt": "2014-05-21T08:51:20Z"
}
]
}
}
## List Users [GET]
Lists users. Only administrators 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, `[{ "status": { "operator": "=", "values": "invited" } }, { "group": { "operator": "=", "values": "Managers" } }, { "name": { "operator": "=", "values": "h.wurst@openproject.com" } }]`) ... JSON specifying filter conditions.
Accepts the same format as returned by the [queries](#queries) endpoint. Currently supported filters are:
+ status: Status the user has
+ group: Name of the group in which to-be-listed users are members.
+ name: Filter users in whose first or last names, or email addresses the given string occurs.
+ sortBy (optional, string, `[["status", "asc"]]`) ... JSON specifying sort criteria.
Accepts the same format as returned by the [queries](#queries) endpoint.
+ Response 200 (application/hal+json)
[Users][]
+ 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
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not allowed to list users."
}
## Create User [POST]
Creates a new user. Only administrators have permission 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.
Valid values for `status`:
1) "active" - In this case a password has to be provided in addition to the other attributes.
2) "invited" - In this case nothing but the email address is required. The rest is optional. An invitation will be sent to the user.
+ Request Create User (application/json)
+ Body
{
"login": "h.wurst",
"email": "h.wurst@openproject.com",
"firstName": "Hans",
"lastName": "Wurst",
"admin": false,
"language": "de",
"status": "active",
"password": "hunter5"
}
+ Request Invite User (application/json)
+ Body
{
"email": "h.wurst@openproject.com",
"firstName": "Hanz",
"status": "invited"
}
+ Response 201
[User][]
+ 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
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not allowed to create new users."
}
+ 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": "The email address is already taken.",
"_embedded": {
"details": {
"attribute": "email"
}
}
}
## User Create Form [/api/v3/users/form]
This endpoint returns a form to allow a guided creation of a new user.
The returned form will be pre-filled with default values for every property, if available.
For more details and all possible responses see the general specification of [Forms](#forms).
## User Create Form [POST]
+ Response 200 (application/hal+json)
+ Body
{
"_links": {
"self": { "href": "/api/v3/users/form" },
"validate": {
"href": "/api/v3/users/form",
"method": "POST"
},
"commit": {
"href": "/api/v3/users",
"method": "POST"
}
},
"_type": "Form",
"_embedded": {
"payload": {
"login": "h.wurst",
"email": "h.wurst@openproject.com",
"firstName": "Hans",
"lastName": "Wurst",
"admin": false,
"language": "de",
"status": "active",
"password": "hunter5"
},
"schema": {
"_type": "Schema",
"id": {
"name": "Id",
"type": "Integer",
"writable": false
},
"login": {
"name": "Login",
"type": "String",
"writable": true,
"required" true,
"minLength": 1,
"maxlength": 256
},
"firstName": {
"name": "First name",
"type": "String",
"writable": true,
"required" true,
"minLength": 1,
"maxLength": 30
},
"lastName": {
"name": "Last name",
"type": "String",
"writable": true,
"required" true,
"minLength": 1,
"maxLength": 30
},
"name": {
"name": "Name",
"type": "String",
"writable": false
},
"email": {
"name": "Email",
"type": "String",
"writable": true,
"required" true,
"minLength": 1,
"maxLength": 60
},
"admin": {
"name": "Administrator",
"type": "Boolean",
"writable": true,
},
"avatar": {
"name": "Avatar",
"type": "Url",
"writable": false,
},
"status": {
"name": "Status",
"type": "String",
"writable": false,
"allowedValues": [
"active",
"invited",
]
}
"language": {
"name": "Language",
"type": "String",
"writable": true,
"allowedValues": [
"en",
"fr",
"de"
]
},
"password": {
"name": "Password",
"type": "String",
"writable": true
},
"createdAt": {
"name": "Created at",
"type": "DateTime",
"writable": false
},
"updatedAt": {
"name": "Updated at",
"type": "DateTime",
"writable": false
},
"customField5" {
"name": "Retired",
"type": "Boolean",
"writable": true
}
}
"validationErrors": {
"subject": {
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:BadExampleError",
"message": "For the purpose of this example we need a validation error. The remainder of the response pretends there were no errors."
}
}
}
}
+ Response 403 (application/hal+json)
Returned if the client does not have sufficient permissions.
**Required permission:** Administrator
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not allowed to create new users."
}