{"id":1818,"date":"2015-03-17T19:23:04","date_gmt":"2015-03-17T19:23:04","guid":{"rendered":"http:\/\/www.doanduyhai.com\/blog\/?p=1818"},"modified":"2017-08-10T16:46:07","modified_gmt":"2017-08-10T16:46:07","slug":"killrchat-rest-api-design","status":"publish","type":"post","link":"https:\/\/www.doanduyhai.com\/blog\/?p=1818","title":{"rendered":"KillrChat REST API design"},"content":{"rendered":"

In this post, I’ll discuss about how KillrChat<\/strong> REST API has been designed to decouple the front and back ends.<\/p>\n

If you have missed the previous posts on KillrChat<\/strong>, please go there<\/a><\/p>\n

The application is completely open-sourced, you can get it here<\/a>
\n<\/p>\n

I User API<\/h1>\n

First we need to deal with the user management API. By user management, we mean:<\/p>\n

    \n
  1. user account creation<\/li>\n
  2. user login (security end-point)<\/li>\n
  3. user logout (security end-point)<\/li>\n
  4. get user details<\/li>\n<\/ol>\n

    The corresponding REST end points are:<\/p>\n\n\n\n\n\n\n\n\n
    Description<\/th>\nHTTP Method<\/th>\nEnd Point<\/th>\nBody\/Returned data<\/th>\nHTTP code<\/th>\n<\/tr>\n<\/thead>\n
    User account creation<\/td>\nPOST<\/td>\n\/users<\/td>\nBody<\/p>\n
    \r\n{\r\n    "login": "jdoe",\r\n    "password": "xxx",\r\n    "firstname": "John",\r\n    "lastname": "DOE",\r\n    "email": "john.doe@dallas.com",\r\n    "bio": "I am John DOE"\r\n}\r\n<\/pre>\n<\/td>\n
    		HTTP 204 or error<\/td>\n<\/tr>\n
    User login (requires HTTPS<\/strong>)<\/td>\nPOST<\/td>\n\/authenticate?j_password:xxx&j_username:jdoe<\/em><\/td>\nN\/A<\/td>\nHTTP 204 or error<\/td>\n<\/tr>\n
    User logout<\/td>\nGET<\/td>\n\/logout<\/td>\nN\/A<\/td>\nHTTP 200<\/td>\n<\/tr>\n
    Get user details<\/td>\nGET<\/td>\n\/users\/:login<\/em><\/td>\nReturned data<\/p>\n
    \r\n{\r\n    "login":"jdoe",\r\n    "firstname":"John",\r\n    "lastname":"DOE",\r\n    "email":"john.doe@dallas.com",\r\n    "bio":"I am John DOE",\r\n    "chatRooms":["Twin_Peaks","Dallas"]\r\n}\r\n<\/pre>\n<\/td>\n
    		\nHTTP 200 or error\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

    II Chat Room API<\/h1>\n

    The chat room lifecycle involves:<\/p>\n

      \n
    1. chat room creation<\/li>\n
    2. get chat room details<\/li>\n
    3. add participant to chat room<\/li>\n
    4. remove participant from chat room<\/li>\n
    5. list n random chat rooms<\/li>\n
    6. remove chat room and kick out all its participants<\/li>\n<\/ol>\n

      The corresponding REST end points are:<\/p>\n\n\n\n\n\n\n\n\n\n\n
      Description<\/th>\nHTTP Method<\/th>\nEnd Point<\/th>\nBody\/Returned data<\/th>\nHTTP code<\/th>\n<\/tr>\n<\/thead>\n
      Chat room creation<\/td>\nPOST<\/td>\n\/rooms\/:roomName<\/em><\/td>\nBody<\/p>\n
      \r\n{\r\n    creator: {\r\n                 login: "jdoe", \r\n                 firstname: "John", \r\n                 lastname: "DOE"\r\n             }, \r\n    banner: "Chat room for Dallas serie"\r\n}\r\n<\/pre>\n<\/td>\n
      		HTTP 204 or error<\/td>\n<\/tr>\n
      Get chat room details<\/td>\nGET<\/td>\n\/rooms\/:roomName<\/em><\/td>\nReturned data<\/p>\n
      \r\n{\r\n    "roomName":"Dallas",\r\n    "creator":{\r\n                 "login":"jdoe",\r\n                 "firstname":"John",\r\n                 "lastname":"DOE"\r\n              },\r\n    "banner":"Anything related to this serie",\r\n    "participants":[\r\n                    {\r\n                        "login":"jdoe",\r\n                        "firstname":"John",\r\n                        "lastname":"DOE"\r\n                    },\r\n                    ...\r\n                   ],\r\n    "creationDate":"2015-03-14 20:31:48"\r\n}\r\n<\/pre>\n<\/td>\n
      		HTTP 200 or error<\/td>\n<\/tr>\n
      Add participant to chat room<\/td>\nPUT<\/td>\n\/rooms\/participant<\/td>\nBody<\/p>\n
      \r\n{\r\n\r\n    "login":"jdoe",\r\n    "firstname":"John",\r\n    "lastname":"DOE"\r\n}\r\n<\/pre>\n<\/td>\n
      		HTTP 204 or error<\/td>\n<\/tr>\n
      Remove participant from chat room<\/td>\nPATCH<\/td>\n\/rooms\/participant<\/td>\nBody<\/p>\n
      \r\n{\r\n\r\n    "login":"jdoe",\r\n    "firstname":"John",\r\n    "lastname":"DOE"\r\n}\r\n<\/pre>\n<\/td>\n
      		HTTP 204 or error<\/td>\n<\/tr>\n
      List 100 random chat rooms<\/td>\nGET<\/td>\n\/rooms?fetchSize=100<\/em><\/td>\nReturned data<\/p>\n
      \r\n[\r\n    {\r\n        "roomName":"Dallas",\r\n        "creator":{\r\n            "login":"jdoe",\r\n            "firstname":"John",\r\n            "lastname":"DOE"\r\n        },\r\n        "banner":"Anything related to this serie",\r\n        "participants":[\r\n            {\r\n                "login":"jdoe",\r\n                "firstname":"John",\r\n                "lastname":"DOE"\r\n            },\r\n            ...\r\n        ],\r\n        "creationDate":"2015-03-14 20:21:39"\r\n    },\r\n    ...\r\n]\r\n<\/pre>\n<\/td>\n
      		HTTP 200 or error<\/td>\n<\/tr>\n
      Remove a chat room<\/td>\nPATCH<\/td>\n\/rooms\/:roomName<\/em><\/td>\nBody<\/p>\n
      \r\n{\r\n    participants: ["jdoe", "hsue", ...]\r\n}\r\n<\/pre>\n<\/td>\n
      		HTTP 204 or error<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

      We use the HTTP verb PATCH<\/strong> instead of DELETE<\/strong> to be able to pass a body. Indeed, the HTTP specification is quite vague about supporting a body content for DELETE<\/strong> messages. Some REST producers\/consumers do support it, others don’t. To circumvent this limitation, PATCH<\/strong> is a possible work-around, although not ideal because we loose the HTTP verb semantics.<\/p><\/blockquote>\n

      III Chat Messages API<\/h1>\n

      Chat messages lifecycle is quite simple:<\/p>\n

        \n
      1. create a new chat message<\/li>\n
      2. fetch a batch of messages starting from a message id<\/li>\n<\/ol>\n

        The corresponding REST end points are:<\/p>\n\n\n\n\n\n\n
        Description<\/th>\nHTTP Method<\/th>\nEnd Point<\/th>\nBody\/Returned data<\/th>\nHTTP code<\/th>\n<\/tr>\n<\/thead>\n
        Create a new chat message<\/td>\nPOST<\/td>\n\/messages<\/td>\nBody<\/p>\n
        \r\n{\r\n    author: {\r\n        login: "jdoe", \r\n        firstname: "John", \r\n        lastname: "DOE"\r\n    }, \r\n    content: "I'm fine, thanks!"\r\n}\r\n<\/pre>\n<\/td>\n
        		HTTP 204 or error<\/td>\n<\/tr>\n
        Fetch previous messages starting from<\/td>\nGET<\/td>\n\/messages?fetchSize=20
        \n&fromMessageId=52278d00-cb0b-…<\/em><\/td>\n        		Returned data<\/p>\n
        \r\n[\r\n    {\r\n        "messageId":"4e831610-cb0b-...",\r\n        "author":{\r\n            "login":"jdoe",\r\n            "firstname":"John",\r\n            "lastname":"DOE"\r\n        },\r\n        "content":"1",\r\n        "systemMessage":false,\r\n        "creationDate":"2015-03-15 13:03:35"\r\n    },\r\n    ...\r\n]\r\n<\/pre>\n<\/td>\n
        		HTTP 200 or error<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

        To be continued …<\/p>\n","protected":false},"excerpt":{"rendered":"

        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…
        Read more<\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":[],"categories":[57,55,10],"tags":[],"_links":{"self":[{"href":"https:\/\/www.doanduyhai.com\/blog\/index.php?rest_route=\/wp\/v2\/posts\/1818"}],"collection":[{"href":"https:\/\/www.doanduyhai.com\/blog\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.doanduyhai.com\/blog\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.doanduyhai.com\/blog\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.doanduyhai.com\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=1818"}],"version-history":[{"count":35,"href":"https:\/\/www.doanduyhai.com\/blog\/index.php?rest_route=\/wp\/v2\/posts\/1818\/revisions"}],"predecessor-version":[{"id":1855,"href":"https:\/\/www.doanduyhai.com\/blog\/index.php?rest_route=\/wp\/v2\/posts\/1818\/revisions\/1855"}],"wp:attachment":[{"href":"https:\/\/www.doanduyhai.com\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=1818"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.doanduyhai.com\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=1818"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.doanduyhai.com\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=1818"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}