Get user

ENDPOINT /api/v0-user/id/[userid] (GET)

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.

Response

This request can respond with following kinds, in addition to the generic kinds (see Introduction):

Kind Meaning HTTP status
haplo:api-v0:user:details The request was successful and a user’s details have been returned 200
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
    • email
    • 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 response

{
    "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", 
            "group:123"
        ]
    }
}