Add s2s POST /publicRooms per MSC2197

See https://github.com/matrix-org/matrix-doc/pull/2197
pull/2305/head
Travis Ralston 5 years ago
parent 5d6113db1e
commit 8d865ca53a

@ -68,3 +68,163 @@ paths:
description: The public room list for the homeserver.
schema:
$ref: "../client-server/definitions/public_rooms_response.yaml"
post:
summary: Gets 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.
Note that this endpoint receives and returns the same format that is seen
in the Client-Server API's ``POST /publicRooms`` endpoint.
operationId: queryPublicRooms
security:
- signedRequest: []
parameters:
- in: body
name: body
required: true
description: |-
Options for which rooms to return.
schema:
type: object
properties:
limit:
type: integer
description: |-
Limit the number of results returned.
since:
type: string
description: |-
A pagination token from a previous request, allowing servers
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).
include_all_networks:
type: boolean
description: |-
Whether or not to include all known networks/protocols from
application services on the homeserver. Defaults to false.
example: false
third_party_instance_id:
type: string
description: |-
The specific third party network/protocol to request from the
homeserver. Can only be used if ``include_all_networks`` is false.
example: "irc"
example: {
"limit": 10,
"filter": {
"generic_search_term": "foo"
},
"include_all_networks": false,
"third_party_instance_id": "irc"
}
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: integer
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: integer
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
}

Loading…
Cancel
Save