document joined_members and joined_rooms endpoints (#999)

api/client-server/list_joined_rooms.yaml

@@ -0,0 +1,57 @@
+# Copyright 2017 Michael Telatynski <7t3chguy@gmail.com>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Room Listing API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
+paths:
+  "/joined_rooms":
+    get:
+      summary: Lists the user's current rooms.
+      description: |-
+        This API returns a list of the user's current rooms.
+      security:
+        - accessToken: []
+      responses:
+        200:
+          description: A list of the rooms the user is in.
+          schema:
+            type: object
+            required: ["joined_rooms"]
+            properties:
+              joined_rooms:
+                type: array
+                description: |-
+                  The ID of each room in which the user has ``joined`` membership.
+                items:
+                  type: string
+          examples:
+            application/json: {
+                "joined_rooms": [
+                  "!foo:example.com"
+                ]
+              }
+      tags:
+        - Room membership

api/client-server/rooms.yaml

@@ -297,3 +297,52 @@ paths:
             member of the room.
       tags:
         - Room participation
+  "/rooms/{roomId}/joined_members":
+    get:
+      summary: Gets the list of currently joined users and their profile data.
+      description:
+        This API returns a map of MXIDs to member info objects for members of the room. The current user must be in the room for it to work, unless it is an Application Service in which case any of the AS's users must be in the room.
+        This API is primarily for Application Services and should be faster to respond than ``/members`` as it can be implemented more efficiently on the server.
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room to get the members of.
+          required: true
+          x-example: "!636q39766251:example.com"
+      security:
+        - accessToken: []
+      responses:
+        200:
+          description: |-
+            A map of MXID to room member objects.
+          examples:
+            application/json: {
+                "joined": {
+                  "@bar:example.com": {
+                    "display_name": "Bar",
+                    "avatar_url": "mxc://riot.ovh/printErCATzZijQsSDWorRaK"
+                  }
+                }
+              }
+          schema:
+            type: object
+            properties:
+              joined:
+                additionalProperties:
+                  title: RoomMember
+                  type: object
+                  properties:
+                    display_name:
+                      type: string
+                      description: The display name of the user this object is representing.
+                    avatar_url:
+                      type: string
+                      description: The mxc avatar url of the user this object is representing.
+                description: A map from user ID to a RoomMember object.
+                type: object
+        403:
+          description: >
+            You aren't a member of the room.
+      tags:
+        - Room participation

changelogs/client_server.rst

@@ -49,6 +49,14 @@
   - Add key distribution APIs, for use with end-to-end encryption.
     (`#894 <https://github.com/matrix-org/matrix-doc/pull/894>`_).
 
+  - New endpoints:
+
+    - ``GET /joined_rooms``
+      (`#999 <https://github.com/matrix-org/matrix-doc/pull/999>`_).
+
+    - ``GET /rooms/{roomId}/joined_members``
+      (`#999 <https://github.com/matrix-org/matrix-doc/pull/999>`_).
+
 - Spec clarifications:
 
   - Add endpoints and logic for invites and third-party invites to the federation

specification/client_server_api.rst

@@ -1260,6 +1260,7 @@ The allowable state transitions of membership are::
   ----------------------------------------------+ +----------------------+
                   /ban
 
+{{list_joined_rooms_cs_http_api}}
 
 Joining rooms
 +++++++++++++