In this post, I’ll discuss about how KillrChat REST API has been designed to decouple the front and back ends.
If you have missed the previous posts on KillrChat, please go there
The application is completely open-sourced, you can get it here
I User API
First we need to deal with the user management API. By user management, we mean:
- user account creation
- user login (security end-point)
- user logout (security end-point)
- get user details
The corresponding REST end points are:
| Description | HTTP Method | End Point | Body/Returned data | HTTP code |
|---|---|---|---|---|
| User account creation | POST | /users | Body
{
"login": "jdoe",
"password": "xxx",
"firstname": "John",
"lastname": "DOE",
"email": "john.doe@dallas.com",
"bio": "I am John DOE"
}
|
HTTP 204 or error |
| User login (requires HTTPS) | POST | /authenticate?j_password:xxx&j_username:jdoe | N/A | HTTP 204 or error |
| User logout | GET | /logout | N/A | HTTP 200 |
| Get user details | GET | /users/:login | Returned data
{
"login":"jdoe",
"firstname":"John",
"lastname":"DOE",
"email":"john.doe@dallas.com",
"bio":"I am John DOE",
"chatRooms":["Twin_Peaks","Dallas"]
}
|
HTTP 200 or error |
II Chat Room API
The chat room lifecycle involves:
- chat room creation
- get chat room details
- add participant to chat room
- remove participant from chat room
- list n random chat rooms
- remove chat room and kick out all its participants
The corresponding REST end points are:
| Description | HTTP Method | End Point | Body/Returned data | HTTP code |
|---|---|---|---|---|
| Chat room creation | POST | /rooms/:roomName | Body
{
creator: {
login: "jdoe",
firstname: "John",
lastname: "DOE"
},
banner: "Chat room for Dallas serie"
}
|
HTTP 204 or error |
| Get chat room details | GET | /rooms/:roomName | Returned data
{
"roomName":"Dallas",
"creator":{
"login":"jdoe",
"firstname":"John",
"lastname":"DOE"
},
"banner":"Anything related to this serie",
"participants":[
{
"login":"jdoe",
"firstname":"John",
"lastname":"DOE"
},
...
],
"creationDate":"2015-03-14 20:31:48"
}
|
HTTP 200 or error |
| Add participant to chat room | PUT | /rooms/participant | Body
{
"login":"jdoe",
"firstname":"John",
"lastname":"DOE"
}
|
HTTP 204 or error |
| Remove participant from chat room | PATCH | /rooms/participant | Body
{
"login":"jdoe",
"firstname":"John",
"lastname":"DOE"
}
|
HTTP 204 or error |
| List 100 random chat rooms | GET | /rooms?fetchSize=100 | Returned data
[
{
"roomName":"Dallas",
"creator":{
"login":"jdoe",
"firstname":"John",
"lastname":"DOE"
},
"banner":"Anything related to this serie",
"participants":[
{
"login":"jdoe",
"firstname":"John",
"lastname":"DOE"
},
...
],
"creationDate":"2015-03-14 20:21:39"
},
...
]
|
HTTP 200 or error |
| Remove a chat room | PATCH | /rooms/:roomName | Body
{
participants: ["jdoe", "hsue", ...]
}
|
HTTP 204 or error |
We use the HTTP verb PATCH instead of DELETE to be able to pass a body. Indeed, the HTTP specification is quite vague about supporting a body content for DELETE messages. Some REST producers/consumers do support it, others don’t. To circumvent this limitation, PATCH is a possible work-around, although not ideal because we loose the HTTP verb semantics.
III Chat Messages API
Chat messages lifecycle is quite simple:
- create a new chat message
- fetch a batch of messages starting from a message id
The corresponding REST end points are:
| Description | HTTP Method | End Point | Body/Returned data | HTTP code |
|---|---|---|---|---|
| Create a new chat message | POST | /messages | Body
{
author: {
login: "jdoe",
firstname: "John",
lastname: "DOE"
},
content: "I'm fine, thanks!"
}
|
HTTP 204 or error |
| Fetch previous messages starting from | GET | /messages?fetchSize=20 &fromMessageId=52278d00-cb0b-… |
Returned data
[
{
"messageId":"4e831610-cb0b-...",
"author":{
"login":"jdoe",
"firstname":"John",
"lastname":"DOE"
},
"content":"1",
"systemMessage":false,
"creationDate":"2015-03-15 13:03:35"
},
...
]
|
HTTP 200 or error |
To be continued …