Thursday, 2 April 2015

Design of Commenting System

This blog describes the design of commenting functionality in an application, through which clinicians can communicate and store notes/comments about a wound/ patient. This includes database design as well as REST API documentation for commenting feature.

Database Design/ER diagram to store data related to comments:
 

Tables Schemas

  • Wound Table: This table has data related to wound/patient.
  • Conversation Table: This table stores the comment thread for a wound.
  • Conversation_message Table: This table stores the individual comment in any comment's thread.
  • User Table: This table contains information about the users who can access the system e.g. Doctor, nurse.
  • Conversation_has_user Table: This is a mapping table between conversation and user.
  • Notification Table: This table contains notifications for a user. Flag is_read is used to indicate whether a notification is read or unread.

Tagging of users in a comment:

This commenting application supports tagging/inviting users in a comment. We can store the message containing user_id in the following form:
some text {{user_id}} more text.
The application logic can resolve {{user_id}} and send notifications accordingly.

Using Links in a comment:

Users can send YouTube links or search results in the comment.

We can handle it in the same way we embed users in the message using expression language - {{youtube_link}} or {{search_link}}

UI layer should have the logic to resolve these expressions and create a preview wherever possible.
 
REST API Documentation

REST APIs provide access to resources (data entities) via URI paths using JSON as its communication format, and the standard HTTP methods.

APIs for Comments

GET /wounds/{wound_id}/comments
Request

Meaning
To get comments for a Wound
HTTP Method
GET
URI
/wounds/{wound_id}/comments

Path Params

Name
Required
Default
Type
wound_id
Y

int

Response
Status
Response
200
application/json (list of comments)
404
{“error” : “Comment doesn’t exist.”}

POST /wounds/{wound_id}/comments
Request

Meaning
To post comment for a Wound
HTTP Method
POST
URI
/wounds/{wound_id}/comments

Path Params
Name
Required
Default
Type
wound_id
Y

int


Message Body
{
“comment” : “message typed by the user”
}

Response

Status
Response
200
application/json (comment posted successfully.)
400
{“error” : “Failed to post the comment.”}


PUT /wounds/{wound_id}/comments/{comment_id}
Request
Meaning
To edit/update comment for a Wound
HTTP Method
PUT
URI
/wounds/{wound_id}/comments/{comment_id}

Path Params

Name
Required
Default
Type
wound_id
Y

int
comment_id
Y

int

Message Body
{
“comment” : “message typed by the user”
}

Response

Status
Response
200
application/json (comment updated successfully.)
400
{“error” : “Failed to update the comment.”}


APIs for notifications

GET /users/{user_id}/notifications
Request
Meaning
To get notifications for a user
HTTP Method
GET
URI
/users/{user_id}/notifications
 
Path Params
Name
Required
Default
Type
user_id
Y

int

Response

Status
Response
200
application/json (list of notifications for a user with each notification containing read/unread flag)
404
{“error” : “Notifications do not exist.”}


POST /users/{user_id}/notifications
Request

Meaning
To  create notification for a user.
HTTP Method
POST
URI
/users/{user_id}/notifications

Path Params

Name
Required
Default
Type
user_id
Y

int

Response
Status
Response
200
application/json (notification created successfully.)
400
{“error” : “Failed to create the notification.”}


Note : Message containing user_id is stored in the following form: “some text {{user_id}} more text”. The application logic can resolve {{user_id}} and send notifications accordingly.


PUT /users/{user_id}/notifications/{notification_id}
Request

Meaning
To mark a notification as read or unread.
HTTP Method
PUT
URI
/users/{user_id}/notifications/{notification_id}

Path Params
 
Name
Required
Default
Type
user_id
Y

int
notification_id
Y

int

Message Body
{
“is_read” : true
}


Response

Status
Response
200
application/json (notification marked read successfully.)
400
{“error” : “Failed to mark the notification as read.”}