KillrChat REST API design

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:

  1. user account creation
  2. user login (security end-point)
  3. user logout (security end-point)
  4. 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:

  1. chat room creation
  2. get chat room details
  3. add participant to chat room
  4. remove participant from chat room
  5. list n random chat rooms
  6. 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:

  1. create a new chat message
  2. 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 …

Leave a Comment

Your email address will not be published. Required fields are marked *