UsersNew - Huddle/huddle-apis GitHub Wiki

Summary

The Membership Users API exposes create, read, update profile, and update status for a Huddle user.

All paths below use the /membership virtual path (gateway / reverse proxy). Clients should call /membership/users/....

Link relations: self; update → .../editable when the caller may edit the profile; update-status → .../status when the caller is a Huddle administrator.

Operations

Method Path Purpose Details
GET /membership/users/{userId} Retrieving a User Jump
GET /membership/users/{userId}/editable Retrieve a User editable profile Jump
PUT /membership/users/{userId}/editable Updating a User Jump
POST /membership/users Creating a User Jump
POST /membership/users/{userId}/status Updating User Status Jump

Retrieving a User

Example

Request:

GET /membership/users/123 HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json

{
    "firstName": "Joe",
    "lastName": "Bloggs",
    "email": "[email protected]",
    "company": "Huddle",
    "role": "Document Writer",
    "aboutMe": "Some interesting information about me",
    "secondaryEmail": "[email protected]",
    "address": "Joe's Desk, Joes's Office, Joe's town...",
    "phone": "01234 567890",
    "mobile": "07712 345678",
    "status": "Active",
    "links": [
        { "rel": "self", "href": "/membership/users/123" },
        { "rel": "update", "href": "/membership/users/123/editable" },
        { "rel": "update-status", "href": "/membership/users/123/status" }
    ]
}

NB: Any fields with null values are omitted in the response body. For example:

{
    "firstName": "Joe",
    "lastName": "Bloggs",
    "email": "[email protected]",
    "company": "Huddle",
    "status": "Active",
    "links": [
        { "rel": "self", "href": "/membership/users/123" },
        { "rel": "update", "href": "/membership/users/123/editable" }
    ]
}

The update-status link is present only when the authenticated actor is a Huddle administrator.

Response properties

Name Description
(body) The User resource fields above

Response link relations

Name Description Methods
self The URI of this user resource GET
update Editable profile (.../editable) GET, PUT
update-status Suspend / activate user (.../status); admin only POST

Other responses

Case Response
Invalid authorization token 401 Unauthorized
Insufficient permissions to view user 403 Forbidden
User does not exist 404 Not Found

Retrieve a user editable profile

Updating a user profile has two stages.

Retrieve editable user profile fields

Example

Request:

GET /membership/users/123/editable HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json

{
    "firstName": "Joe",
    "lastName": "Bloggs",
    "email": "[email protected]",
    "company": "Huddle",
    "role": "Document Writer",
    "aboutMe": "Some interesting information about me",
    "secondaryEmail": "[email protected]",
    "address": "Joe's Desk, Joes's Office, Joe's town...",
    "phone": "01234 567890",
    "mobile": "07712 345678",
    "links": [
        { "rel": "self", "href": "/membership/users/123/editable" },
        { "rel": "parent", "href": "/membership/users/123" },
        { "rel": "update", "href": "/membership/users/123/editable" }
    ]
}

Response link relations (editable)

Name Description Methods
self Editable resource for this user GET
parent Full user resource GET
update Submit profile update PUT

Other responses (get editable)

Case Response
Email cannot be changed (validation) 400 Bad Request
First name, last name, or email not supplied 400 Bad Request
Invalid authorization token 401 Unauthorized
Insufficient permissions 403 Forbidden
User does not exist 404 Not Found
Email already in use 409 Conflict

Update a user profile

Example

Request:

PUT /membership/users/123/editable HTTP/1.1
Accept: application/vnd.huddle.data+json
Content-Type: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
    "firstName": "Joe",
    "lastName": "Bloggs",
    "email": "[email protected]",
    "company": "Huddle - Development",
    "role": "Document Writer",
    "aboutMe": "Some interesting information about me",
    "secondaryEmail": "[email protected]",
    "address": "Joe's Desk, Joes's Office, Joe's town...",
    "phone": "01234 567890",
    "mobile": "07712 345678"
}

Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json
Content-Location: /membership/users/123

{
    "firstName": "Joe",
    "lastName": "Bloggs",
    "email": "[email protected]",
    "company": "Huddle",
    "role": "Document Writer",
    "aboutMe": "Some interesting information about me",
    "secondaryEmail": "[email protected]",
    "address": "Joe's Desk, Joes's Office, Joe's town...",
    "phone": "01234 567890",
    "mobile": "07712 345678",
    "status": "Active",
    "links": [
        { "rel": "self", "href": "/membership/users/123" },
        { "rel": "update", "href": "/membership/users/123/editable" }
    ]
}

Example where the email change conflicts with workspace whitelist rules:

HTTP/1.1 400 Bad Request
Content-Type: application/vnd.huddle.data+json
Content-Location: /membership/users/123

{
    "errors": [
        { "email": "self", "message": "Existing email address is part of a workspace whitelist. It cannot be changed." }
    ]
}

Other responses (put editable)

Case Response
Email cannot be changed 400 Bad Request
Empty required fields 400 Bad Request
Invalid authorization token 401 Unauthorized
Insufficient permissions to update user 403 Forbidden
User does not exist 404 Not Found
Email already in use 409 Conflict

Creating a User

Only Huddle support / administrators can create a user. Email (username) and password are required; other fields are optional.

Example request

POST /membership/users HTTP/1.1
Content-Type: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
    "email": "[email protected]",
    "password": "4jbef5£$nfhjvd",
    "firstName": "Joe",
    "lastName": "Bloggs",
    "company": "Huddle",
    "role": "Document Writer",
    "aboutMe": "Some interesting information about me",
    "secondaryEmail": "[email protected]",
    "address": "Joe's Desk, Joes's Office, Joe's town...",
    "phone": "01234 567890",
    "mobile": "07712 345678"
}

Example response

HTTP/1.1 201 Created
Content-Type: application/vnd.huddle.data+json

{
    "firstName": "Joe",
    "lastName": "Bloggs",
    "email": "[email protected]",
    "company": "Huddle",
    "role": "Document Writer",
    "aboutMe": "Some interesting information about me",
    "secondaryEmail": "[email protected]",
    "address": "Joe's Desk, Joes's Office, Joe's town...",
    "phone": "01234 567890",
    "mobile": "07712 345678",
    "status": "Active",
    "links": [
        { "rel": "self", "href": "/membership/users/123" },
        { "rel": "update", "href": "/membership/users/123/editable" }
    ]
}

NB: As with user retrieval, null fields are omitted in the response body.

Other responses (create)

Case Response
Missing required fields or invalid fields 400 Bad Request
Invalid authorization token 401 Unauthorized
Insufficient permissions (not Huddle administrator) 403 Forbidden
Email already in use 409 Conflict

Updating User Status

Sets user status to active or suspended. The JSON body includes status (e.g. Active or Suspended).

Request

POST /membership/users/123/status HTTP/1.1
Accept: application/vnd.huddle.data+json
Content-Type: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
    "status": "Suspended"
}
Status Description
Active User is active
Suspended User is suspended (not active)

(Lowercase strings may be accepted depending on JSON serializer configuration; enum names are Active / Suspended.)

Response

HTTP/1.1 204 No Content
Content-Location: /membership/users/123

Other responses (status)

Case Response
Status not recognised 400 Bad Request
Invalid authorization token 401 Unauthorized
Insufficient permissions to update user 403 Forbidden
User does not exist 404 Not Found

Related

  • User — legacy XML user document and schema (Actor self); not the same shape as the Membership JSON user resource above.