-
Notifications
You must be signed in to change notification settings - Fork 0
User Documentation
This document provides information about using the REST API this code provides. The below sections logically group queries into different categories.
This API uses JSON, and whenever a request contains a JSON content body the Content-Type: application/json header must be provided.
Sections:
A user can belong to many groups (become a member), can send messages to other people, and can read messages from other users.
Retrieve every user. Since this can get pretty big, think about using the optional limit and offset query parameters for pagination.
GET /users?limit=<limit>&offset=<offset>
Example response:
[
{
"userId": 1,
"username": "sender",
"created": "2013-11-16 01:33:06"
},
{
"userId": 2,
"username": "recipient",
"created": "2013-11-16 01:33:06"
},
{
"userId": 3,
"username": "other",
"created": "2013-11-16 01:33:06"
}
]
If no users exist the response will be No Content (204) and have no response body.
GET /users/{userId}
Example response:
{
"userId": 3,
"username": "other",
"created": "2013-11-16 01:33:06"
}
Get a list of groups the user is a member of.
GET /users/{userId}/groups
Example response:
[
{
"groupId": 1,
"groupName": "apple"
},
{
"groupId": 3,
"groupName": "all"
}
]
If the user is not a member of any group the response will be No Content (204) and have no response body.
POST /users
Content-Type: application/json
{
"username": "foobar"
}
Usernames are unique, so it is important handle error conditions that come with attempting to create a user with a username that another user already uses.
Error codes:
- Access Denied (403) -- Trying to create a user that already exists.
- Bad Request (400) -- Malformed request.
This request provides no response (other than a 200) and deletes the specified user.
DELETE /users/{userId}
A group is a named collection of users. Groups can have many users and a user can be in many groups. Groups can be the target of a send message call, meaning every member currently in the group will receive the message.
Like the number of users, the number of groups can also get large. Consider using limit and offset below for pagination.
GET /groups?limit=<limit>&offset=<offset>
Example response:
[
{
"groupId": 1,
"groupName": "apple",
"created": "2013-11-16 01:33:06"
},
{
"groupId": 2,
"groupName": "zebra",
"created": "2013-11-16 01:33:06"
},
{
"groupId": 3,
"groupName": "all",
"created": "2013-11-16 01:33:06"
}
]
If no groups exist the response will be No Content (204) and have no response body.
Get information about an individual group:
GET /groups/{groupId}
Example response:
{
"groupId": 1,
"groupName": "apple",
"created": "2013-11-16 01:33:06"
}
This will create a group "foobar" with no users:
POST /groups
Content-Type: application/json
{
"groupName": "foobar"
}
Group names are unique, so it is important handle error conditions that come with attempting to create a group with a groupName that another group already uses.
Error codes:
- Access Denied (403) -- Trying to create a group that already exists.
- Bad Request (400) -- Malformed request.
This request provides no response (other than a 200) and deletes the specified group.
DELETE /groups/{groupId}
GET /group/{groupId}/members
Example response:
[
1,
2
]
The numbers above represent userIds. If the group is empty (no members) the response will be No Content (204) and have no response body.
Make a user a member of a group.
PUT /groups/{groupId}/members/{userId}
Remove a user from a group's membership.
DELETE /groups/{groupId}/members/{userId}
An inbox is a collection of messages sent to a user. Messages are marked as read automatically when they are opened (using the Open Message call).
Get a list of messages in a user's inbox. This call can return a lot of data, so consider using the limit and offset query parameters to paginate the results appropriately.
GET /users/{userId}/inbox
Example response:
[
{
"messageId": 1,
"fromUser": 1,
"subject": "First Message Subject",
"created": "2013-11-16 01:36:26",
"toUser": 2,
"read": 0
},
{
"messageId": 2,
"fromUser": 1,
"subject": "Second Message Subject",
"created": "2013-11-16 01:36:26",
"toUser": 2,
"read": 1
},
{
"messageId": 3,
"fromUser": 1,
"subject": "Third Message Subject",
"created": "2013-11-16 01:36:26",
"toUser": 2,
"read": 0
}
]
If the user's inbox is empty (no messages) the response will be No Content (204) and have no response body.
To get the body of a message, you'll have to open it. Using this command automatically sets "read" to true.
GET /users/{userId}/inbox/{messageId}
Example response:
{
"messageId": 1,
"fromUser": 1,
"subject": "First Message Subject",
"created": "2013-11-16 01:36:26",
"toUser": 2,
"read": 1,
"body": "First body."
}
Remove a message from a user's inbox.
DELETE /users/{userId}/inbox/{messageId}
There are three different ways to send a message: broadcast to every user in the system, send a message to a list of groups, or send a message to a list of users. Only one of these methods may be used for a given message.
POST /users/{userId}/send
Content-Type: application/json
{
"broadcast": true,
"subject": "Message Subject",
"body": "Message body."
}
POST /users/{userId}/send
Content-Type: application/json
{
"toGroups": ["groupA", "groupB"],
"subject": "Message Subject",
"body": "Message body."
}
POST /users/{userId}/send
Content-Type: application/json
{
"toUsers": ["userA", "userB"],
"subject": "Message Subject",
"body": "Message body."
}