From d81d0dbd1dd8401b0e183b6487f5704ffad316bc Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Thu, 29 Sep 2016 10:35:04 +0100 Subject: [PATCH 01/18] Spec canonical alias key --- api/client-server/list_public_rooms.yaml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/api/client-server/list_public_rooms.yaml b/api/client-server/list_public_rooms.yaml index 253cfe07..a34f50b3 100644 --- a/api/client-server/list_public_rooms.yaml +++ b/api/client-server/list_public_rooms.yaml @@ -54,6 +54,10 @@ paths: Aliases of the room. May be empty. items: type: string + canonical_alias: + type: string + description: |- + The canonical alias of the room, if any. May be null. name: type: string description: |- From 877a6cfeb4d9cc9e5304b0f1d8da748fbd3b19d4 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Thu, 29 Sep 2016 10:47:37 +0100 Subject: [PATCH 02/18] Spec new query params for /publicRooms --- api/client-server/list_public_rooms.yaml | 36 ++++++++++++++++++++---- 1 file changed, 30 insertions(+), 6 deletions(-) diff --git a/api/client-server/list_public_rooms.yaml b/api/client-server/list_public_rooms.yaml index a34f50b3..c6795426 100644 --- a/api/client-server/list_public_rooms.yaml +++ b/api/client-server/list_public_rooms.yaml @@ -32,6 +32,25 @@ paths: Lists the public rooms on the server. This API returns paginated responses. + parameters: + - in: query + name: limit + type: number + description: |- + Limit the number of results returned, ordered by number of + memebers in the room. Defaults to no limit. + - in: query + name: since + type: string + description: |- + A pagination token from a previous request, allowing clients to + get the next batch of rooms. + - 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. @@ -87,14 +106,18 @@ 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, if there are any more results. + prev_batch: type: string description: |- - A pagination token for the response. + A pagination token for the response, if there are any more results. + total_room_count_estimate: + type: number + description: |- + An estimate on the total number of public rooms. examples: application/json: |- { @@ -110,8 +133,9 @@ paths: "world_readable": true } ], - "start": "p190q", - "end": "p1902" + "next_batch": "p190q", + "prev_batch": "p1902", + "total_room_count_estimate": 115 } 400: description: > From 130ea855760c9a5c412f6d437aff7fbbe032ed8b Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Thu, 29 Sep 2016 10:59:14 +0100 Subject: [PATCH 03/18] Spec POST /publicRooms --- api/client-server/list_public_rooms.yaml | 132 +++++++++++++++++++++++ 1 file changed, 132 insertions(+) diff --git a/api/client-server/list_public_rooms.yaml b/api/client-server/list_public_rooms.yaml index c6795426..597dde29 100644 --- a/api/client-server/list_public_rooms.yaml +++ b/api/client-server/list_public_rooms.yaml @@ -140,5 +140,137 @@ paths: 400: description: > The request body is malformed or the room alias specified is already taken. + post: + summary: Lists the public rooms on the server with optional filter. + description: |- + Lists the public rooms on the server. + + This API returns paginated responses. + 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, ordered by number of + memebers in the room. Defaults to no limit. + since: + type: string + description: |- + A pagination token from a previous request, allowing clients to + get the next batch of rooms. + filter: + type: object + description: |- + Optional filtering of the returned rooms. + properties: + generic_search_term: + type: string + description: |- + A string to search for in the room metadata, e.g. name, + topic, canonical alias etc. + 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. + properties: + chunk: + title: "PublicRoomsChunks" + type: array + description: |- + A paginated chunk of public rooms. + items: + type: object + title: "PublicRoomsChunk" + 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. May be null. + name: + type: string + description: |- + The name of the room, if any. May be null. + 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. May be null. + 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, if there are any more results. + prev_batch: + type: string + description: |- + A pagination token for the response, if there are any more results. + total_room_count_estimate: + type: number + description: |- + An estimate on the total number of public rooms. + 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 From c05ee18f58b69ed1201c9578c1c9f569e20fbbd6 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Thu, 29 Sep 2016 11:06:57 +0100 Subject: [PATCH 04/18] Add title and update description --- api/client-server/list_public_rooms.yaml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/api/client-server/list_public_rooms.yaml b/api/client-server/list_public_rooms.yaml index 597dde29..1a277fb6 100644 --- a/api/client-server/list_public_rooms.yaml +++ b/api/client-server/list_public_rooms.yaml @@ -143,9 +143,11 @@ paths: post: summary: Lists the public rooms on the server with optional filter. description: |- - Lists the public rooms on the server. + Lists the public rooms on the server, with optional filter. This API returns paginated responses. + security: + - accessToken: [] parameters: - in: query name: server @@ -173,6 +175,7 @@ paths: get the next batch of rooms. filter: type: object + title: "Filter" description: |- Optional filtering of the returned rooms. properties: From 0dc94d5c140c6e95100728e141d0cedd40026243 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Thu, 29 Sep 2016 16:58:00 +0100 Subject: [PATCH 05/18] Expand on description of pagination tokens --- api/client-server/list_public_rooms.yaml | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/api/client-server/list_public_rooms.yaml b/api/client-server/list_public_rooms.yaml index 1a277fb6..5d09d45a 100644 --- a/api/client-server/list_public_rooms.yaml +++ b/api/client-server/list_public_rooms.yaml @@ -109,11 +109,15 @@ paths: next_batch: type: string description: |- - A pagination token for the response, if there are any more results. + 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, if there are any more results. + 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: |- @@ -244,11 +248,15 @@ paths: next_batch: type: string description: |- - A pagination token for the response, if there are any more results. + 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, if there are any more results. + 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: |- From 212a4b5fce8be8ce607e31a8304ed3b50c06df13 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Thu, 29 Sep 2016 17:02:00 +0100 Subject: [PATCH 06/18] Add changelog entry --- changelogs/client_server.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index d7384e31..111c2f6b 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -35,6 +35,8 @@ - Add top-level ``account_data`` key to the responses to ``GET /sync`` and ``GET /initialSync`` (`#380 `_). + - Add pagination and filter support to ``/publicRooms`` + (`#388 `_). r0.2.0 ====== From e854757c98f0b1441a7b2522db3eaa3013a72eb2 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Thu, 29 Sep 2016 17:09:46 +0100 Subject: [PATCH 07/18] Mark required fields as required --- api/client-server/list_public_rooms.yaml | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/api/client-server/list_public_rooms.yaml b/api/client-server/list_public_rooms.yaml index 5d09d45a..2072f92a 100644 --- a/api/client-server/list_public_rooms.yaml +++ b/api/client-server/list_public_rooms.yaml @@ -57,6 +57,7 @@ paths: schema: type: object description: A list of the rooms on the server. + required: ["chunk"] properties: chunk: title: "PublicRoomsChunks" @@ -66,6 +67,7 @@ paths: items: type: object title: "PublicRoomsChunk" + required: ["room_id"] properties: aliases: type: array @@ -187,7 +189,7 @@ paths: type: string description: |- A string to search for in the room metadata, e.g. name, - topic, canonical alias etc. + topic, canonical alias etc. (Optional). example: |- {"limit": 10, "filter": {"generic_search_term": "foo"}} responses: @@ -196,6 +198,7 @@ paths: schema: type: object description: A list of the rooms on the server. + required: ["chunk"] properties: chunk: title: "PublicRoomsChunks" @@ -205,6 +208,7 @@ paths: items: type: object title: "PublicRoomsChunk" + required: ["room_id"] properties: aliases: type: array From e8b21f357f89a574c81883387929415efa8a4318 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Thu, 29 Sep 2016 17:18:34 +0100 Subject: [PATCH 08/18] Explicitlty mention total_room_count_estimate --- api/client-server/list_public_rooms.yaml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/api/client-server/list_public_rooms.yaml b/api/client-server/list_public_rooms.yaml index 2072f92a..d5826d69 100644 --- a/api/client-server/list_public_rooms.yaml +++ b/api/client-server/list_public_rooms.yaml @@ -123,7 +123,8 @@ paths: total_room_count_estimate: type: number description: |- - An estimate on the total number of public rooms. + An estimate on the total number of public rooms, if the + server has an estimate. examples: application/json: |- { @@ -264,7 +265,8 @@ paths: total_room_count_estimate: type: number description: |- - An estimate on the total number of public rooms. + An estimate on the total number of public rooms, if the + server has an estimate. examples: application/json: |- { From 06649b652d67dded8fe393cccd9d0829d09169f6 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Fri, 30 Sep 2016 14:18:13 +0100 Subject: [PATCH 09/18] Mark booleans as required. Remove mention that things may be null --- api/client-server/list_public_rooms.yaml | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/api/client-server/list_public_rooms.yaml b/api/client-server/list_public_rooms.yaml index d5826d69..5982e7fd 100644 --- a/api/client-server/list_public_rooms.yaml +++ b/api/client-server/list_public_rooms.yaml @@ -67,7 +67,11 @@ paths: items: type: object title: "PublicRoomsChunk" - required: ["room_id"] + required: + - room_id + - num_joined_users + - world_readable + - guest_can_join properties: aliases: type: array @@ -78,11 +82,11 @@ paths: canonical_alias: type: string description: |- - The canonical alias of the room, if any. May be null. + 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: |- @@ -94,7 +98,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: |- From 5e99f4753d6021a30748b3c83d55c190acb0fd8f Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Fri, 30 Sep 2016 14:20:35 +0100 Subject: [PATCH 10/18] Update changelog --- changelogs/client_server.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index 111c2f6b..33cc8c73 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -35,7 +35,9 @@ - Add top-level ``account_data`` key to the responses to ``GET /sync`` and ``GET /initialSync`` (`#380 `_). - - Add pagination and filter support to ``/publicRooms`` + - 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 `_). r0.2.0 From a66a744c451711c4f760c399ba4101b9de3af9af Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Fri, 30 Sep 2016 14:28:40 +0100 Subject: [PATCH 11/18] Fix typo. Change responses in both places --- api/client-server/list_public_rooms.yaml | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/api/client-server/list_public_rooms.yaml b/api/client-server/list_public_rooms.yaml index 5982e7fd..c65da9c7 100644 --- a/api/client-server/list_public_rooms.yaml +++ b/api/client-server/list_public_rooms.yaml @@ -69,7 +69,7 @@ paths: title: "PublicRoomsChunk" required: - room_id - - num_joined_users + - num_joined_members - world_readable - guest_can_join properties: @@ -213,7 +213,11 @@ paths: items: type: object title: "PublicRoomsChunk" - required: ["room_id"] + required: + - room_id + - num_joined_members + - world_readable + - guest_can_join properties: aliases: type: array @@ -224,11 +228,11 @@ paths: canonical_alias: type: string description: |- - The canonical alias of the room, if any. May be null. + 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: |- @@ -240,7 +244,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: |- From a5bb182c677d5ee08a5734e5530c373ecbeec603 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Fri, 30 Sep 2016 14:30:13 +0100 Subject: [PATCH 12/18] Explicitly mention that directio of pagination is specified by the token --- api/client-server/list_public_rooms.yaml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/api/client-server/list_public_rooms.yaml b/api/client-server/list_public_rooms.yaml index c65da9c7..302e3269 100644 --- a/api/client-server/list_public_rooms.yaml +++ b/api/client-server/list_public_rooms.yaml @@ -124,6 +124,8 @@ paths: 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. + The direction of pagination is specified solely by which token + is supplied, rather than via an explicit flag. total_room_count_estimate: type: number description: |- @@ -270,6 +272,8 @@ paths: 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. + The direction of pagination is specified solely by which token + is supplied, rather than via an explicit flag. total_room_count_estimate: type: number description: |- From 9d0960b206aed683813d521fa96e0fe21d5432cb Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Tue, 11 Oct 2016 14:24:46 +0100 Subject: [PATCH 13/18] Better wording --- api/client-server/list_public_rooms.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/client-server/list_public_rooms.yaml b/api/client-server/list_public_rooms.yaml index 302e3269..e76bd7ab 100644 --- a/api/client-server/list_public_rooms.yaml +++ b/api/client-server/list_public_rooms.yaml @@ -44,7 +44,7 @@ paths: type: string description: |- A pagination token from a previous request, allowing clients to - get the next batch of rooms. + get the next (or previous) batch of rooms. - in: query name: server type: string @@ -190,7 +190,7 @@ paths: type: object title: "Filter" description: |- - Optional filtering of the returned rooms. + Filter to apply to the results. properties: generic_search_term: type: string From de68c167b646d795c4d6f51c5664e7f2e6777089 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Tue, 11 Oct 2016 14:27:49 +0100 Subject: [PATCH 14/18] Add tags for GET endpoint --- api/client-server/list_public_rooms.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/api/client-server/list_public_rooms.yaml b/api/client-server/list_public_rooms.yaml index e76bd7ab..9eb5bf65 100644 --- a/api/client-server/list_public_rooms.yaml +++ b/api/client-server/list_public_rooms.yaml @@ -153,6 +153,8 @@ paths: 400: description: > The request body is malformed or the room alias specified is already taken. + tags: + - Room discovery post: summary: Lists the public rooms on the server with optional filter. description: |- From 71c1fc5ec0ede8efa3b15c844aad886ed1644a51 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Tue, 11 Oct 2016 14:28:32 +0100 Subject: [PATCH 15/18] Remove spurious 400 result --- api/client-server/list_public_rooms.yaml | 6 ------ 1 file changed, 6 deletions(-) diff --git a/api/client-server/list_public_rooms.yaml b/api/client-server/list_public_rooms.yaml index 9eb5bf65..62d9c014 100644 --- a/api/client-server/list_public_rooms.yaml +++ b/api/client-server/list_public_rooms.yaml @@ -150,9 +150,6 @@ paths: "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 post: @@ -300,8 +297,5 @@ paths: "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 From cafa9a01fd8276198e02ab97fc648686bbb0f4c0 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Tue, 11 Oct 2016 14:29:20 +0100 Subject: [PATCH 16/18] Move explanation of lack of direction param --- api/client-server/list_public_rooms.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/client-server/list_public_rooms.yaml b/api/client-server/list_public_rooms.yaml index 62d9c014..fbdf3fde 100644 --- a/api/client-server/list_public_rooms.yaml +++ b/api/client-server/list_public_rooms.yaml @@ -45,6 +45,8 @@ paths: 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 @@ -124,8 +126,6 @@ paths: 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. - The direction of pagination is specified solely by which token - is supplied, rather than via an explicit flag. total_room_count_estimate: type: number description: |- From d66792d5cae131bdc7310d7469210dde05279617 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Fri, 14 Oct 2016 10:31:06 +0100 Subject: [PATCH 17/18] Mention order of returned results --- api/client-server/list_public_rooms.yaml | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/api/client-server/list_public_rooms.yaml b/api/client-server/list_public_rooms.yaml index fbdf3fde..d2d6eb17 100644 --- a/api/client-server/list_public_rooms.yaml +++ b/api/client-server/list_public_rooms.yaml @@ -31,14 +31,14 @@ 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 members, with the largest rooms first. parameters: - in: query name: limit type: number description: |- - Limit the number of results returned, ordered by number of - memebers in the room. Defaults to no limit. + Limit the number of results returned. - in: query name: since type: string @@ -157,7 +157,8 @@ paths: description: |- Lists the public rooms on the server, with optional filter. - This API returns paginated responses. + This API returns paginated responses. The rooms are ordered by the number + of members, with the largest rooms first. security: - accessToken: [] parameters: @@ -178,13 +179,12 @@ paths: limit: type: number description: |- - Limit the number of results returned, ordered by number of - memebers in the room. Defaults to no limit. + Limit the number of results returned. since: type: string description: |- A pagination token from a previous request, allowing clients to - get the next batch of rooms. + get the next or previous batch of rooms. filter: type: object title: "Filter" From c175039a08edcaa9cb23ff5ad0c91a3f037811cc Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Mon, 21 Nov 2016 13:08:41 +0000 Subject: [PATCH 18/18] Final public_rooms clarifications * order by *joined* members * clarify pagination direction behaviour --- api/client-server/list_public_rooms.yaml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/api/client-server/list_public_rooms.yaml b/api/client-server/list_public_rooms.yaml index d2d6eb17..3aa449d3 100644 --- a/api/client-server/list_public_rooms.yaml +++ b/api/client-server/list_public_rooms.yaml @@ -32,7 +32,7 @@ paths: Lists the public rooms on the server. This API returns paginated responses. The rooms are ordered by the number - of members, with the largest rooms first. + of joined members, with the largest rooms first. parameters: - in: query name: limit @@ -158,7 +158,7 @@ paths: Lists the public rooms on the server, with optional filter. This API returns paginated responses. The rooms are ordered by the number - of members, with the largest rooms first. + of joined members, with the largest rooms first. security: - accessToken: [] parameters: @@ -183,8 +183,10 @@ paths: since: type: string description: |- - A pagination token from a previous request, allowing clients to - get the next or previous batch of rooms. + 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" @@ -271,8 +273,6 @@ paths: 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. - The direction of pagination is specified solely by which token - is supplied, rather than via an explicit flag. total_room_count_estimate: type: number description: |-