Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-04-13 14:44:10 +02:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Merge pull request #388 from matrix-org/erikj/public_rooms

Browse source 
New /publicRoom APIs
This commit is contained in:
Richard van der Hoff 2016-11-21 13:13:45 +00:00 committed by GitHub
parent 9debd7c1ad c175039a08
commit 02a8715197
2 changed files with 201 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

209
api/client-server/list_public_rooms.yaml
View file

@ -31,13 +31,35 @@ paths:
description: |- description: |-
Lists the public rooms on the server. 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: responses:
200: 200:
description: A list of the rooms on the server. description: A list of the rooms on the server.
schema: schema:
type: object type: object
description: A list of the rooms on the server. description: A list of the rooms on the server.
required: ["chunk"]
properties: properties:
chunk: chunk:
title: "PublicRoomsChunks" title: "PublicRoomsChunks"
@ -47,6 +69,11 @@ paths:
items: items:
type: object type: object
title: "PublicRoomsChunk" title: "PublicRoomsChunk"
required:
- room_id
- num_joined_members
- world_readable
- guest_can_join
properties: properties:
aliases: aliases:
type: array type: array
@ -54,10 +81,14 @@ paths:
Aliases of the room. May be empty. Aliases of the room. May be empty.
items: items:
type: string type: string
canonical_alias:
type: string
description: |-
The canonical alias of the room, if any.
name: name:
type: string type: string
description: |- description: |-
The name of the room, if any. May be null. The name of the room, if any.
num_joined_members: num_joined_members:
type: number type: number
description: |- description: |-
@ -69,7 +100,7 @@ paths:
topic: topic:
type: string type: string
description: |- description: |-
The topic of the room, if any. May be null. The topic of the room, if any.
world_readable: world_readable:
type: boolean type: boolean
description: |- description: |-
@ -83,14 +114,23 @@ paths:
avatar_url: avatar_url:
type: string type: string
description: The URL for the room's avatar, if one is set. description: The URL for the room's avatar, if one is set.
start: next_batch:
type: string type: string
description: |- description: |-
A pagination token for the response. A pagination token for the response. The absence of this token
end: means there are no more results to fetch and the client should
stop paginating.
prev_batch:
type: string type: string
description: |- 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: examples:
application/json: |- application/json: |-
{ {
@ -106,11 +146,156 @@ paths:
"world_readable": true "world_readable": true
} }
], ],
"start": "p190q", "next_batch": "p190q",
"end": "p1902" "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: tags:
- Room discovery - Room discovery

4
changelogs/client_server.rst
View file

@ -39,6 +39,10 @@
- Require that User-Interactive auth fallback pages call - Require that User-Interactive auth fallback pages call
``window.postMessage`` to notify apps of completion ``window.postMessage`` to notify apps of completion
(`#398 <https://github.com/matrix-org/matrix-doc/pull/398>`_). (`#398 <https://github.com/matrix-org/matrix-doc/pull/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 <https://github.com/matrix-org/matrix-doc/pull/388>`_).
- Spec clarifications: - Spec clarifications: