diff --git a/api/client-server/list_public_rooms.yaml b/api/client-server/list_public_rooms.yaml index 253cfe07..3aa449d3 100644 --- a/api/client-server/list_public_rooms.yaml +++ b/api/client-server/list_public_rooms.yaml @@ -31,13 +31,35 @@ paths: description: |- Lists the public rooms on the server. - This API returns paginated responses. + This API returns paginated responses. The rooms are ordered by the number + of joined members, with the largest rooms first. + parameters: + - in: query + name: limit + type: number + description: |- + Limit the number of results returned. + - in: query + name: since + type: string + description: |- + A pagination token from a previous request, allowing clients to + get the next (or previous) batch of rooms. + The direction of pagination is specified solely by which token + is supplied, rather than via an explicit flag. + - in: query + name: server + type: string + description: |- + The server to fetch the public room lists from. Defaults to the + local server. responses: 200: description: A list of the rooms on the server. schema: type: object description: A list of the rooms on the server. + required: ["chunk"] properties: chunk: title: "PublicRoomsChunks" @@ -47,6 +69,11 @@ paths: items: type: object title: "PublicRoomsChunk" + required: + - room_id + - num_joined_members + - world_readable + - guest_can_join properties: aliases: type: array @@ -54,10 +81,14 @@ paths: Aliases of the room. May be empty. items: type: string + canonical_alias: + type: string + description: |- + The canonical alias of the room, if any. name: type: string description: |- - The name of the room, if any. May be null. + The name of the room, if any. num_joined_members: type: number description: |- @@ -69,7 +100,7 @@ paths: topic: type: string description: |- - The topic of the room, if any. May be null. + The topic of the room, if any. world_readable: type: boolean description: |- @@ -83,14 +114,23 @@ paths: avatar_url: type: string description: The URL for the room's avatar, if one is set. - start: + next_batch: type: string description: |- - A pagination token for the response. - end: + A pagination token for the response. The absence of this token + means there are no more results to fetch and the client should + stop paginating. + prev_batch: type: string description: |- - A pagination token for the response. + A pagination token that allows fetching previous results. The + absence of this token means there are no results before this + batch, i.e. this is the first batch. + total_room_count_estimate: + type: number + description: |- + An estimate on the total number of public rooms, if the + server has an estimate. examples: application/json: |- { @@ -106,11 +146,156 @@ paths: "world_readable": true } ], - "start": "p190q", - "end": "p1902" + "next_batch": "p190q", + "prev_batch": "p1902", + "total_room_count_estimate": 115 + } + tags: + - Room discovery + post: + summary: Lists the public rooms on the server with optional filter. + description: |- + Lists the public rooms on the server, with optional filter. + + This API returns paginated responses. The rooms are ordered by the number + of joined members, with the largest rooms first. + security: + - accessToken: [] + parameters: + - in: query + name: server + type: string + description: |- + The server to fetch the public room lists from. Defaults to the + local server. + - in: body + name: body + required: true + description: |- + Options for which rooms to return. + schema: + type: object + properties: + limit: + type: number + description: |- + Limit the number of results returned. + since: + type: string + description: |- + A pagination token from a previous request, allowing clients + to get the next (or previous) batch of rooms. The direction + of pagination is specified solely by which token is supplied, + rather than via an explicit flag. + filter: + type: object + title: "Filter" + description: |- + Filter to apply to the results. + properties: + generic_search_term: + type: string + description: |- + A string to search for in the room metadata, e.g. name, + topic, canonical alias etc. (Optional). + example: |- + {"limit": 10, "filter": {"generic_search_term": "foo"}} + responses: + 200: + description: A list of the rooms on the server. + schema: + type: object + description: A list of the rooms on the server. + required: ["chunk"] + properties: + chunk: + title: "PublicRoomsChunks" + type: array + description: |- + A paginated chunk of public rooms. + items: + type: object + title: "PublicRoomsChunk" + required: + - room_id + - num_joined_members + - world_readable + - guest_can_join + properties: + aliases: + type: array + description: |- + Aliases of the room. May be empty. + items: + type: string + canonical_alias: + type: string + description: |- + The canonical alias of the room, if any. + name: + type: string + description: |- + The name of the room, if any. + num_joined_members: + type: number + description: |- + The number of members joined to the room. + room_id: + type: string + description: |- + The ID of the room. + topic: + type: string + description: |- + The topic of the room, if any. + world_readable: + type: boolean + description: |- + Whether the room may be viewed by guest users without joining. + guest_can_join: + type: boolean + description: |- + Whether guest users may join the room and participate in it. + If they can, they will be subject to ordinary power level + rules like any other user. + avatar_url: + type: string + description: The URL for the room's avatar, if one is set. + next_batch: + type: string + description: |- + A pagination token for the response. The absence of this token + means there are no more results to fetch and the client should + stop paginating. + prev_batch: + type: string + description: |- + A pagination token that allows fetching previous results. The + absence of this token means there are no results before this + batch, i.e. this is the first batch. + total_room_count_estimate: + type: number + description: |- + An estimate on the total number of public rooms, if the + server has an estimate. + examples: + application/json: |- + { + "chunk": [ + { + "aliases": ["#murrays:cheese.bar"], + "avatar_url": "mxc://bleeker.street/CHEDDARandBRIE", + "guest_can_join": false, + "name": "CHEESE", + "num_joined_members": 37, + "room_id": "!ol19s:bleecker.street", + "topic": "Tasty tasty cheese", + "world_readable": true + } + ], + "next_batch": "p190q", + "prev_batch": "p1902", + "total_room_count_estimate": 115 } - 400: - description: > - The request body is malformed or the room alias specified is already taken. tags: - Room discovery diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index 875d5ce1..69ce3661 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -39,6 +39,10 @@ - Require that User-Interactive auth fallback pages call ``window.postMessage`` to notify apps of completion (`#398 `_). + - Add pagination and filter support to ``/publicRooms``. Change response to + omit fields rather than return ``null``. Add estimate of total number of + rooms in list. + (`#388 `_). - Spec clarifications: