Skip to content

Commit 1a8fbfe

Browse files
turt2liveturt2live
authored
Merge pull request #2305 from matrix-org/travis/spec/ss-search
Add s2s POST /publicRooms per MSC2197
2 parents 6d60b04 + 5cb7599 commit 1a8fbfe

File tree

2 files changed

+161
-0
lines changed

2 files changed

+161
-0
lines changed

‎api/server-server/public_rooms.yaml

+160
Original file line numberDiff line numberDiff line change
@@ -68,3 +68,163 @@ paths:
6868
description: The public room list for the homeserver.
6969
schema:
7070
$ref: "../client-server/definitions/public_rooms_response.yaml"
71+
post:
72+
summary: Gets the public rooms on the server with optional filter.
73+
description: |-
74+
Lists the public rooms on the server, with optional filter.
75+
76+
This API returns paginated responses. The rooms are ordered by the number
77+
of joined members, with the largest rooms first.
78+
79+
Note that this endpoint receives and returns the same format that is seen
80+
in the Client-Server API's ``POST /publicRooms`` endpoint.
81+
operationId: queryPublicRooms
82+
security:
83+
- signedRequest: []
84+
parameters:
85+
- in: body
86+
name: body
87+
required: true
88+
description: |-
89+
Options for which rooms to return.
90+
schema:
91+
type: object
92+
properties:
93+
limit:
94+
type: integer
95+
description: |-
96+
Limit the number of results returned.
97+
since:
98+
type: string
99+
description: |-
100+
A pagination token from a previous request, allowing servers
101+
to get the next (or previous) batch of rooms. The direction
102+
of pagination is specified solely by which token is supplied,
103+
rather than via an explicit flag.
104+
filter:
105+
type: object
106+
title: "Filter"
107+
description: |-
108+
Filter to apply to the results.
109+
properties:
110+
generic_search_term:
111+
type: string
112+
description: |-
113+
A string to search for in the room metadata, e.g. name,
114+
topic, canonical alias etc. (Optional).
115+
include_all_networks:
116+
type: boolean
117+
description: |-
118+
Whether or not to include all known networks/protocols from
119+
application services on the homeserver. Defaults to false.
120+
example: false
121+
third_party_instance_id:
122+
type: string
123+
description: |-
124+
The specific third party network/protocol to request from the
125+
homeserver. Can only be used if ``include_all_networks`` is false.
126+
example: "irc"
127+
example: {
128+
"limit": 10,
129+
"filter": {
130+
"generic_search_term": "foo"
131+
},
132+
"include_all_networks": false,
133+
"third_party_instance_id": "irc"
134+
}
135+
responses:
136+
200:
137+
description: A list of the rooms on the server.
138+
schema:
139+
type: object
140+
description: A list of the rooms on the server.
141+
required: ["chunk"]
142+
properties:
143+
chunk:
144+
title: "PublicRoomsChunks"
145+
type: array
146+
description: |-
147+
A paginated chunk of public rooms.
148+
items:
149+
type: object
150+
title: "PublicRoomsChunk"
151+
required:
152+
- room_id
153+
- num_joined_members
154+
- world_readable
155+
- guest_can_join
156+
properties:
157+
aliases:
158+
type: array
159+
description: |-
160+
Aliases of the room. May be empty.
161+
items:
162+
type: string
163+
canonical_alias:
164+
type: string
165+
description: |-
166+
The canonical alias of the room, if any.
167+
name:
168+
type: string
169+
description: |-
170+
The name of the room, if any.
171+
num_joined_members:
172+
type: integer
173+
description: |-
174+
The number of members joined to the room.
175+
room_id:
176+
type: string
177+
description: |-
178+
The ID of the room.
179+
topic:
180+
type: string
181+
description: |-
182+
The topic of the room, if any.
183+
world_readable:
184+
type: boolean
185+
description: |-
186+
Whether the room may be viewed by guest users without joining.
187+
guest_can_join:
188+
type: boolean
189+
description: |-
190+
Whether guest users may join the room and participate in it.
191+
If they can, they will be subject to ordinary power level
192+
rules like any other user.
193+
avatar_url:
194+
type: string
195+
description: The URL for the room's avatar, if one is set.
196+
next_batch:
197+
type: string
198+
description: |-
199+
A pagination token for the response. The absence of this token
200+
means there are no more results to fetch and the client should
201+
stop paginating.
202+
prev_batch:
203+
type: string
204+
description: |-
205+
A pagination token that allows fetching previous results. The
206+
absence of this token means there are no results before this
207+
batch, i.e. this is the first batch.
208+
total_room_count_estimate:
209+
type: integer
210+
description: |-
211+
An estimate on the total number of public rooms, if the
212+
server has an estimate.
213+
examples:
214+
application/json: {
215+
"chunk": [
216+
{
217+
"aliases": ["#murrays:cheese.bar"],
218+
"avatar_url": "mxc://bleeker.street/CHEDDARandBRIE",
219+
"guest_can_join": false,
220+
"name": "CHEESE",
221+
"num_joined_members": 37,
222+
"room_id": "!ol19s:bleecker.street",
223+
"topic": "Tasty tasty cheese",
224+
"world_readable": true
225+
}
226+
],
227+
"next_batch": "p190q",
228+
"prev_batch": "p1902",
229+
"total_room_count_estimate": 115
230+
}

‎changelogs/server_server/newsfragments/2035.new

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Add new ``POST /publicRooms`` endpoint for filtering the room directory.

0 commit comments

Comments
 (0)