Users resource (Data API 18.7)
Summary
Http Method | Resource | Description |
---|---|---|
GET | /users/this | Action to get the user password expiration information. |
PATCH | /users/this/password | Action to change a user password. |
GET | /users/{login} | Action to get a user. |
PUT | /users/{login} | Action to create or overwrite a user. If a user with the given login already exists, the existing user will be overwritten. If no such login exists, a new user is created. |
PATCH | /users/{login} | Action to update a user. |
DELETE | /users/{login} | Action to delete a single user. |
Get user password expiration information
Action to get the user password expiration information.Url
GET https://hostname:port/dw/data/v18_7/users/this
Formats
json, xml
Authentication
Name | Description |
---|---|
OAuth | Authentication via OAuth token. |
Response Document
In case of a failure Fault Document is returned.
Faults
Status | Type | Arguments | Description |
---|---|---|---|
401 |
UserNotAvailableException
|
If the user provided by the OAuth token cannot be found. | |
401 |
UserIsLockedException
|
If the user profile is currently locked. |
Sample
REQUEST:
GET /s/-/dw/data/v18_7/users/this HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Type: application/json; charset=UTF-8
# in case of success:
RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
"_type": "user",
"disabled": false,
"email": "[email protected]",
"first_name": "Ocapi",
"last_name": "MultiSite-Full-ReadWriteSitePreferences",
"locked": false,
"login": "MultiSite-Full-ReadWriteSitePreferences",
"password_expiration_date": "2016-01-14T16:48:07Z",
"password_modification_date": "2016-04-14T16:48:07Z",
"preferred_data_locale": "default",
"preferred_uilocale": "default"
}
# in case of failure:
RESPONSE:
HTTP/1.1 401 UNAUTHORIZED
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
"_v" : "18.7",
"fault" :
{
"type" : "UserNotAvailableException",
"message" : "No user was provided with the OAuth token."
}
}
Change the user password
Action to change a user password.Url
PATCH https://hostname:port/dw/data/v18_7/users/this/password
Formats
json, xml
Authentication
Name | Description |
---|---|
OAuth | Authentication via OAuth token. |
Request Document
Response Document
In case of a failure Fault Document is returned.
Faults
Status | Type | Arguments | Description |
---|---|---|---|
400 |
PasswordPolicyViolationException
|
If the new password doesn't meet the acceptance crtiteria of a user password. | |
400 |
PasswordNotValidForReuseException
|
If the same new password was set recently before. | |
400 |
InvalidPasswordException
|
If the provided current user password is invalid. | |
401 |
UserNotAvailableException
|
If the user provided by the OAuth token cannot be found. | |
401 |
UserIsLockedException
|
If the user profile is currently locked. |
Customization
This Resource supports server-side customization.
Extension Point | Method Detail |
---|---|
dw.ocapi.data.users.afterPATCH |
afterPatch (login : String , email : String ) : Status The function is called after the users password is updated.
|
Sample
REQUEST:
PATCH /s/-/dw/data/v18_7/users/this/password HTTP/1.1
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Host: example.com
{
"current_password" : "MyOldPWD1!"
"password": "MyNewPWD1!"
}
# in case of success:
RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
"_type": "user",
"disabled": false,
"email": "[email protected]",
"first_name": "Ocapi",
"last_name": "MultiSite-Full-ReadWriteSitePreferences",
"locked": false,
"login": "MultiSite-Full-ReadWriteSitePreferences",
"password_expiration_date": "2016-01-14T16:48:07Z",
"password_modification_date": "2016-04-14T16:48:07Z",
"preferred_data_locale": "default",
"preferred_uilocale": "default"
}
# in case of failure:
RESPONSE:
HTTP/1.1 401 UNAUTHORIZED
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
"_v" : "18.7",
"fault" :
{
"type" : "UserNotAvailableException",
"message" : "No user was provided with the OAuth token."
}
}
HTTP/1.1 400 BAD REQUEST
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
"_v" : "18.7",
"fault" :
{
"type" : "InvalidPasswordException",
"message" : "The current user password is invalid."
}
}
HTTP/1.1 400 BAD REQUEST
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
"_v" : "18.7",
"fault" :
{
"type" : "PasswordPolicyViolationException",
"message" : "The provided new password does not meet the acceptance criteria."
}
}
HTTP/1.1 400 BAD REQUEST
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
"_v" : "18.7",
"fault" :
{
"type" : "PasswordNotValidForReuseException",
"message" : "The password was recently used and is not valid for reuse."
}
}
Get User
Action to get a user.Url
GET https://hostname:port/dw/data/v18_7/users/{login}
Formats
json, xml
Authentication
Name | Description |
---|---|
OAuth | Authentication via OAuth token. |
Response Document
Path Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
login | String | login of the user | minLength=1 |
In case of a failure Fault Document is returned.
Faults
Status | Type | Arguments | Description |
---|---|---|---|
404 |
UserNotFoundException
|
login (String) |
If no user with the specified login could be found. |
Sample
REQUEST:
GET /s/-/dw/data/v18_7/users/someUser HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Type: application/json; charset=UTF-8
# in case of success:
RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
"_type": "user",
"disabled": false,
"email": "[email protected]",
"first_name": "John",
"last_name": "Doe",
"locked": false,
"login": "someUser",
"password_expiration_date": "2016-01-14T16:48:07Z",
"password_modification_date": "2016-04-14T16:48:07Z",
"preferred_data_locale": "default",
"preferred_ui_locale": "en-US",
"roles": ["FirstRole", "SecondRole"]
}
# in case of failure:
RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
"_v" : "18.7",
"fault" :
{
"type" : "UserNotFoundException",
"message" : "No user with login 'someUser' was found."
}
}
Create User
Action to create or overwrite a user. If a user with the given login already exists, the existing user will be overwritten. If no such login exists, a new user is created.Url
PUT https://hostname:port/dw/data/v18_7/users/{login}
Formats
json, xml
Authentication
Name | Description |
---|---|
OAuth | Authentication via OAuth token. |
Request Document
Response Document
Path Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
login | String | login of the user | minLength=1 |
In case of a failure Fault Document is returned.
Faults
Status | Type | Arguments | Description |
---|---|---|---|
400 |
PasswordPolicyViolationException
|
If the password doesn't meet the acceptance crtiteria of a user password. | |
400 |
IdConflictException
|
bodyID (String) urlID (String) |
If the login in the request URL is different from the login in the request body. |
400 |
UnknownLocaleException
|
locale (String) |
If either the Preferred UI Locale or the Preferred Data Locale are unknown. |
403 |
UserOperationNotAllowedException
|
login (String) |
If creation or replacement of a user with the given login is not allowed. |
Sample
REQUEST:
PUT /s/-/dw/data/v18_7/users/someUser HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
x-dw-resource-state: 2168cf2b4fbf88ce601bd09c18.7b6aaff14e9360eca75fbbf347818.71574df
Content-Type: application/json; charset=UTF-8
{
"disabled": false,
"email": "[email protected]",
"first_name": "John",
"last_name": "Doe",
"login": "someUser",
"password": "My$ecurePassword3"
"preferred_data_locale": "default",
"preferred_ui_locale": "en-US",
"roles": ["FirstRole", "SecondRole"]
}
# in case of success:
RESPONSE:
HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
"_v": "18.7",
"_resource_state": "4553edb0fa1ea413fa9646bb376182c8eeb721f47e7a418.7691ea3d598f2159",
"_type": "user",
"disabled": false,
"email": "[email protected]",
"first_name": "John",
"last_name": "Doe",
"locked": false,
"login": "someUser",
"password_modification_date": "2016-04-14T16:48:07Z",
"preferred_data_locale": "default",
"preferred_ui_locale": "en-US",
"roles": ["FirstRole", "SecondRole"]
}
# in case of failure:
RESPONSE:
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
"_v" : "18.7",
"fault" :
{
"type" : "PasswordPolicyViolationException",
"message" : "The provided new password does not meet the requirements."
}
}
RESPONSE:
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
"_v" : "18.7",
"fault" :
{
"type" : "UnknownLocaleException",
"message" : "The locale 'aa' is unknown."
}
}
RESPONSE:
HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
"_v" : "18.7",
"fault" :
{
"type" : "UserOperationNotAllowedException",
"message" : "The operation is not allowed for the user with login 'someUser'."
}
}
RESPONSE:
HTTP/1.1 409 Conflict
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
"_v" : "18.7",
"fault" :
{
"type" : "IdConflictException",
"message" : "The ID in the request body ('myUser') does not match the ID in the URL ('someUser')."
}
}
Create User
Action to update a user.Url
PATCH https://hostname:port/dw/data/v18_7/users/{login}
Formats
json, xml
Authentication
Name | Description |
---|---|
OAuth | Authentication via OAuth token. |
Request Document
Response Document
Path Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
login | String | login of the user | minLength=1 |
In case of a failure Fault Document is returned.
Faults
Status | Type | Arguments | Description |
---|---|---|---|
400 |
IdConflictException
|
bodyID (String) urlID (String) |
If the login in the request URL is different from the login in the request body. |
400 |
UnknownLocaleException
|
locale (String) |
If either the Preferred UI Locale or the Preferred Data Locale are unknown. |
403 |
UserOperationNotAllowedException
|
login (String) |
If creation or replacement of a user with the given login is not allowed. |
404 |
UserNotFoundException
|
login (String) |
If no user with the specified login could be found. |
Sample
REQUEST:
PATCH /s/-/dw/data/v18_7/users/someUser HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
x-dw-resource-state: 2168cf2b4fbf88ce601bd09c18.7b6aaff14e9360eca75fbbf347818.71574df
Content-Type: application/json; charset=UTF-8
{
"disabled": false,
"email": "[email protected]",
"first_name": "John",
"last_name": "Doe",
"login": "someUser",
"preferred_data_locale": "default",
"preferred_ui_locale": "en-US",
"roles": ["ThirdRole"]
}
# in case of success:
RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
"_v": "18.7",
"_resource_state": "4553edb0fa1ea413fa9646bb376182c8eeb721f47e7a418.7691ea3d598f2159",
"_type": "user",
"disabled": false,
"email": "[email protected]",
"first_name": "John",
"last_name": "Doe",
"locked": false,
"login": "someUser",
"password_modification_date": "2016-04-14T16:48:07Z",
"preferred_data_locale": "default",
"preferred_ui_locale": "en-US",
"roles": ["ThirdRole"]
}
# in case of failure:
RESPONSE:
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
"_v" : "18.7",
"fault" :
{
"type" : "UnknownLocaleException",
"message" : "The locale 'aa' is unknown."
}
}
RESPONSE:
HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
"_v" : "18.7",
"fault" :
{
"type" : "UserOperationNotAllowedException",
"message" : "The operation is not allowed for the user with login 'someUser'."
}
}
RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
"_v" : "18.7",
"fault" :
{
"type" : "UserNotFoundException",
"message" : "No user with login 'someUser' was found."
}
}
RESPONSE:
HTTP/1.1 409 Conflict
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
"_v" : "18.7",
"fault" :
{
"type" : "IdConflictException",
"message" : "The ID in the request body ('myUser') does not match the ID in the URL ('someUser')."
}
}
Delete User
Action to delete a single user.Url
DELETE https://hostname:port/dw/data/v18_7/users/{login}
Formats
json, xml
Authentication
Name | Description |
---|---|
OAuth | Authentication via OAuth token. |
Path Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
login | String | login of the user | minLength=1 |
In case of a failure Fault Document is returned.
Faults
Status | Type | Arguments | Description |
---|---|---|---|
404 |
UserNotFoundException
|
login (String) |
If no user with the specified login could be found. |
Sample
REQUEST:
DELETE /s/-/dw/data/v18_7/users/someUser HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Type: application/json; charset=UTF-8
# in case of success:
RESPONSE:
HTTP/1.1 204 No Content
# in case of failure:
RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
"_v" : "18.7",
"fault" :
{
"type" : "UserNotFoundException",
"message" : "No user with login 'someUser' was found."
}
}