Update user
/api/v0-user/id/[userid]
(POST)When generating URLs, [userid]
is the id of a user SecurityPrincipal
. It is optional.
If [userid]
is not included, you must include a tag query.
Tag queries are included in the parameters of the request, and can include multiple tags. For each tag you want to query on, the name of the paramter should be the name of the tag, prefixed by tag:
. The value of the parameter should be the value of the tag for the users you care about. For instance, a username query could look like: tag:username=abc123
. The username
tag is special, and is used for uniquely identifying users throughout the system.
When using tag queries for this endpoint, you should only use queries that you expect to return a single user. To get a list of all users with a set of tags, use the Find by tag endpoint.
The body of the request should be a JSON document containing only the fields that you wish to change for the user. The fields which can be updated by this API are:
- nameFirst
- nameLast
- ref
- localeId
- tags
- directGroupMembership
Apart from directGroupMembership
, all the fields correspond directly to the equivalent field on the SecurityPrincipal
. directGroupMembership
is the equivalent of directGroupIds
, but returns an array of group API codes instead of group IDs.
Example request body
{ "nameFirst":"First", "nameLast":"Last", "email":"first.last@example.com", "ref":"890qv", "localeId":"en", "tags": { "username": "abc123", "flag": "other" }, "directGroupMembership":[ "haplo:group:example" ] }
Response
This request can respond with following kinds, in addition to the generic kinds (see Introduction):
Kind | Meaning | HTTP status |
haplo:api-v0:user:update |
The request was successful and the updated user’s details have been returned | 200 |
haplo:api-v0:user:update-failed |
The user could not be created with the provided details. | 400 |
haplo:api-v0:user:no-such-user |
No user could be found with the requested id. | 404 |
haplo:api-v0:user:no-tag-query-provided |
A tag query was expected for this request, but was not provided. | 400 |
haplo:api-v0:user:no-user-found |
No user could be found that matched the tag query provided. | 404 |
haplo:api-v0:user:multiple-users-found |
Multiple users were found matching the tag query, but this endpoint expects to return only one user. Tag queries for this endpoint should be on uniquely identifying tags. | 404 |
Along with the standard success
and kind
fields (see Introduction for explanation), the response has the following structure:
- user
- id
- nameFirst
- nameLast
- name
- code
- ref
- isGroup
- isActive
- isSuperUser
- isServiceUser
- isAnonymous
- localeId
- tags
- directGroupMembership
Apart from directGroupMembership
, all the fields correspond directly to the equivalent field on the SecurityPrincipal
. directGroupMembership
is the equivalent of directGroupIds
, but returns an array of group API codes instead of group IDs.
Example
{ "success": true, "kind": "haplo:api-v0:user:details", "user": { "id":130, "nameFirst":"First", "nameLast":"Last", "name":"First Last", "code":null, "email":"first.last@example.com", "ref":null, "isGroup":false, "isActive":true, "isSuperUser":false, "isServiceUser":false, "isAnonymous":false, "localeId":"en", "tags": { "username": "abc123", "flag": "other" }, "directGroupMembership":[ "haplo:group:example" ] } }