feat: GET /api/v3/chats/:roomId

public/openapi/components/schemas/Chats.yaml

@@ -11,4 +11,72 @@ RoomObject:
       type: string
     groupChat:
       type: boolean
-      description: whether the chat room is a group chat or not
+      description: whether the chat room is a group chat or not
+MessageObject:
+  type: object
+  properties:
+    content:
+      type: string
+      description: A chat message's content, parsed like a post (so probably outputs html)
+    timestamp:
+      type: number
+    fromuid:
+      type: number
+    roomId:
+      type: number
+    deleted:
+      type: boolean
+    system:
+      type: boolean
+    edited:
+      type: number
+    timestampISO:
+      type: string
+    editedISO:
+      type: string
+    messageId:
+      type: number
+    fromUser:
+      type: object
+      properties:
+        uid:
+          type: number
+          description: A user identifier
+        username:
+          type: string
+          description: A friendly name for a given user account
+          example: Dragon Fruit
+        userslug:
+          type: string
+          description: An URL-safe variant of the username (i.e. lower-cased, spaces removed, etc.)
+          example: dragon-fruit
+        picture:
+          type: string
+          description: A URL pointing to a picture to be used as the user's avatar
+          example: 'https://images.unsplash.com/photo-1560070094-e1f2ddec4337?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=256&h=256&q=80'
+        banned:
+          type: boolean
+          description: Whether a user is banned or not
+          example: false
+        displayname:
+          type: string
+          description: This is either username or fullname depending on forum and user settings
+          example: Dragon Fruit
+        icon:text:
+          type: string
+          description: A single-letter representation of a username. This is used in the
+            auto-generated icon given to users
+            without an avatar
+        icon:bgColor:
+          type: string
+          description: A six-character hexadecimal colour code assigned to the user. This
+            value is used in conjunction with
+            `icon:text` for the user's
+            auto-generated icon
+          example: "#f44336"
+        banned_until_readable:
+          type: string
+          description: An ISO 8601 formatted date string representing the moment a ban will be lifted, or the words "Not Banned"
+          example: Not Banned
+        deleted:
+          type: boolean

public/openapi/write/chats/roomId.yaml

@@ -14,4 +14,83 @@ head:
     '200':
       description: chat room found
     '404':
-      description: chat room not found
+      description: chat room not found
+get:
+  tags:
+    - chats
+  summary: get a chat room
+  description: This operation retrieves a chat room's data including users and messages
+  parameters:
+    - in: path
+      name: roomId
+      schema:
+        type: number
+      required: true
+      description: a valid chat room id
+      example: 1
+  responses:
+    '200':
+      description: Chat room successfully retrieved
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              status:
+                $ref: ../../components/schemas/Status.yaml#/Status
+              response:
+                allOf:
+                  - $ref: ../../components/schemas/Chats.yaml#/RoomObject
+                  - $ref: ../../components/schemas/Chats.yaml#/MessageObject
+                  - type: object
+                    properties:
+                      isOwner:
+                        type: boolean
+                      users:
+                        type: array
+                        items:
+                          type: object
+                          properties:
+                            uid:
+                              type: number
+                              description: A user identifier
+                            username:
+                              type: string
+                              description: A friendly name for a given user account
+                            picture:
+                              nullable: true
+                              type: string
+                            status:
+                              type: string
+                            displayname:
+                              type: string
+                              description: This is either username or fullname depending on forum and user settings
+                            icon:text:
+                              type: string
+                              description: A single-letter representation of a username. This is used in the
+                                auto-generated icon given to users
+                                without an avatar
+                            icon:bgColor:
+                              type: string
+                              description: A six-character hexadecimal colour code assigned to the user. This
+                                value is used in conjunction with
+                                `icon:text` for the user's
+                                auto-generated icon
+                              example: "#f44336"
+                            isOwner:
+                              type: boolean
+                      canReply:
+                        type: boolean
+                      groupChat:
+                        type: boolean
+                      usernames:
+                        type: string
+                        description: User-friendly depiction of the users within the chat room
+                      maximumUsersInChatRoom:
+                        type: number
+                      maximumChatMessageLength:
+                        type: number
+                      showUserInput:
+                        type: boolean
+                      isAdminOrGlobalMod:
+                        type: boolean

src/controllers/write/chats.js

@@ -27,7 +27,12 @@ Chats.exists = async (req, res) => {
 };
 
 Chats.get = async (req, res) => {
-	// ...
+	const roomObj = await messaging.loadRoom(req.uid, {
+		uid: req.query.uid || req.uid,
+		roomId: req.params.roomId,
+	});
+
+	helpers.formatApiResponse(200, res, roomObj);
 };
 
 Chats.post = async (req, res) => {

src/routes/write/chats.js

@@ -14,7 +14,7 @@ module.exports = function () {
 	setupApiRoute(router, 'post', '/', [...middlewares, middleware.checkRequired.bind(null, ['uids'])], controllers.write.chats.create);
 
 	setupApiRoute(router, 'head', '/:roomId', [...middlewares, middleware.assert.room], controllers.write.chats.exists);
-	// setupApiRoute(router, 'get', '/:roomId', [...middlewares, middleware.assert.room], controllers.write.chats.get);
+	setupApiRoute(router, 'get', '/:roomId', [...middlewares, middleware.assert.room], controllers.write.chats.get);
 	// setupApiRoute(router, 'post', '/:roomId', [...middlewares, middleware.assert.room], controllers.write.chats.post);
 	// // no route for room deletion, reserved just in case...
 

src/socket.io/modules.js

@@ -100,6 +100,8 @@ function rateLimitExceeded(socket) {
 }
 
 SocketModules.chats.loadRoom = async function (socket, data) {
+	sockets.warnDeprecated(socket, 'GET /api/v3/chats/:roomId');
+
 	if (!data || !data.roomId) {
 		throw new Error('[[error:invalid-data]]');
 	}