Users - Huddle/huddle-apis GitHub Wiki

Summary

The Membership Users API is a representation of a given User within Huddle

Status

Operation
Retrieving a User
Updating User Profile
Creating a User
Updating User Status

Operations

Retrieving a User

Request:

GET /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": "/users/123" },
        { "rel" : "update", "href": "/users/123/editable" }
        { "rel" : "update-status", "href": "/users/123/status" } 
    ]
}

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

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

Response Properties:

Name	Description
user	The User resource

Response Link Relations:

Name	Description	Methods
self	The URI of this User resource	GET
update	If you have permission, the URI to get editable fields to Update a User Profile	GET
update	If you have permission, the URI to Update a User Profile	PUT

Other Responses:

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

Updating a User

Updating a User Profile has two stages.

Retrieve editable User Profile fields

Retrieve Example

The following example requests User Profile editable fields for User with Id 123.

Request:

GET /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": "/users/123/editable" },
        { "rel" : "parent", "href": "/users/123" },
        { "rel" : "update", "href": "/users/123/editable" }
    ]
}

Response Properties:

Name	Description
user	The editable fields for the user, and their current values

Response Link Relations:

Name	Description	Methods
self	The URI of editable fields for this User's Profile	GET
parent	The URI of this User resource	GET
update	If you have permission, the URI to Update a User Profile	PUT

Other Responses:

Name	Response
Email address can't be changed	400 Bad request
First name, last name, or Email not supplied	400 Bad Request
Invalid authorization token	401 Unauthorized
Insufficient permissions to view User	403 Forbidden
User does not exist	404 Not Found
Users email is already in use	409 Conflict

Update a User Profile

Update Example

The following examples updates a User Profile for User with Id 123.

Request:

PUT /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: /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": "/users/123" },
        { "rel" : "update", "href": "/users/123/editable" }
    ]
}

Example where user's email address change means that domain whitelisting would be affected.

Response:

HTTP/1.1 400 Bad Request
Content-Type: application/vnd.huddle.data+json
Content-Location: /users/123
{
    "errors": [
        { "email" : "self", "message": "Existing email address is part of a workspace whitelist. It cannot be changed." }
    ]
}

Response Properties:

Name	Description
user	The User resource

Response Link Relations:

Name	Description	Methods
self	The URI of this User resource	GET
update	If you have permission, the URI to get editable fields to Update a User Profile	GET
update	If you have permission, the URI to Update a User Profile	PUT

Other Responses:

Name	Response
Email address 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 can create a user. An email address (that will be the user's username) and a password are required, all other fields are optional.

Example request:

POST /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": "/users/123" },
        { "rel" : "update", "href": "/users/123/editable" }
    ]
}

NB As with user retrieval, any fields with null values will be omitted in the response body.

Response Properties:

Name	Description
user	The User resource

Response Link Relations:

Name	Description	Methods
self	The URI of this User resource	GET
update	If you have permission, the URI to get editable fields to Update a User Profile	GET
update	If you have permission, the URI to Update a User Profile	PUT

Other Responses:

Name	Response
Missing required fields or invalid fields	400 Bad Request
Invalid authorization token	401 Unauthorized
Insufficient permissions to create User (only Huddle administrators can create a user)	403 Forbidden
Email already in use	409 Conflict

Updating User Status

Allows user status to be set to active or suspended.

Request:

POST /users/123/status HTTP/1.1  
Accept: application/json  
Authorization: Bearer frootymcnooty/vonbootycherooty  

{  
    "status": "suspended"  
}

Status	Description
active	Set user status to active
suspended	Set user status to suspended (not active)

Response:

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

Other Responses:

Name	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