Skip to content

Commit 7bcc3ec

Browse files
JohennesJohennes
authored
Spec PR - MSC3266: Room Summary API (#2125)
Signed-off-by: Johannes Marbach <[email protected]>
1 parent 866c05f commit 7bcc3ec

File tree

8 files changed

+212
-32
lines changed

8 files changed

+212
-32
lines changed

‎changelogs/client_server/newsfragments/2125.feature‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Add `/_matrix/client/v1/room_summary/{roomIdOrAlias}` and extend `/_matrix/client/v1/rooms/{roomId}/hierarchy` with the new optional properties `allowed_room_ids`, `encryption` and `room_version` as per [MSC3266](https://github.com/matrix-org/matrix-spec-proposals/pull/3266).

‎changelogs/server_server/newsfragments/2125.feature‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Extend `/_matrix/federation/v1/hierarchy/{roomId}` with the new optional properties `encryption` and `room_version` as per [MSC3266](https://github.com/matrix-org/matrix-spec-proposals/pull/3266).

‎content/client-server-api/_index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2892,6 +2892,10 @@ that are not `world_readable` regardless of their visibility.
28922892

28932893
{{% http-api spec="client-server" api="list_public_rooms" %}}
28942894

2895+
### Room Summaries
2896+
2897+
{{% http-api spec="client-server" api="room_summary" %}}
2898+
28952899
## User Data
28962900

28972901
### User Directory

‎data/api/client-server/definitions/public_rooms_chunk.yaml‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,6 @@ properties:
6161
example: "public"
6262
room_type:
6363
type: string
64-
x-addedInMatrixVersion: "1.4"
6564
description: |-
6665
The `type` of room (from [`m.room.create`](/client-server-api/#mroomcreate)), if any.
6766
required:

‎data/api/client-server/definitions/room_summary.yaml‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# Copyright 2025 The Matrix.org Foundation C.I.C.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
type: object
16+
title: RoomSummary
17+
allOf:
18+
- $ref: public_rooms_chunk.yaml
19+
- type: object
20+
properties:
21+
room_type:
22+
type: string
23+
description: The `type` of room (from
24+
[`m.room.create`](/client-server-api/#mroomcreate)),
25+
if any.
26+
allowed_room_ids:
27+
type: array
28+
items:
29+
type: string
30+
description: |-
31+
If the room is a [restricted room](/server-server-api/#restricted-rooms), these are the room IDs which
32+
are specified by the join rules. Empty or omitted otherwise.
33+
encryption:
34+
type: string
35+
enum:
36+
- "m.megolm.v1.aes-sha2"
37+
description: |-
38+
The encryption algorithm to be used to encrypt messages sent in the
39+
room.
40+
room_version:
41+
description: The version of the room.
42+
type: string
43+
44+
required:
45+
- room_id
46+
- num_joined_members
47+
- world_readable
48+
- guest_can_join

‎data/api/client-server/room_summary.yaml‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# Copyright 2025 The Matrix.org Foundation C.I.C.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
openapi: 3.1.0
15+
info:
16+
title: Matrix Client-Server Room Summary API
17+
version: 1.0.0
18+
paths:
19+
"/room_summary/{roomIdOrAlias}":
20+
get:
21+
x-addedInMatrixVersion: "1.15"
22+
summary: Retrieves a summary for a room.
23+
description: |-
24+
Retrieves a summary for a room.
25+
26+
Clients should note that requests for rooms where the user's membership
27+
is `invite` or `knock` might yield outdated, partial or even no data
28+
since the server may not have access to the current state of the room.
29+
30+
Servers MAY allow unauthenticated access to this API if at least one of
31+
the following conditions holds true:
32+
33+
- The room has a [join rule](#mroomjoin_rules) of `public`, `knock` or
34+
`knock_restricted`.
35+
- The room has a `world_readable` [history visibility](#room-history-visibility).
36+
37+
Servers should consider rate limiting requests that require a federation
38+
request more heavily if the client is unauthenticated.
39+
operationId: getRoomSummary
40+
security:
41+
- signedRequest: []
42+
parameters:
43+
- in: path
44+
name: roomIdOrAlias
45+
description: The room identifier or alias to summarise.
46+
required: true
47+
example: "#monkeys:matrix.org"
48+
schema:
49+
type: string
50+
- in: query
51+
name: via
52+
description: |-
53+
The servers to attempt to request the summary from when
54+
the local server cannot generate it (for instance, because
55+
it has no local user in the room).
56+
example:
57+
- matrix.org
58+
- elsewhere.ca
59+
schema:
60+
type: array
61+
items:
62+
type: string
63+
responses:
64+
"200":
65+
description: A summary of the room.
66+
content:
67+
application/json:
68+
schema:
69+
description: A summary of the room.
70+
allOf:
71+
- $ref: ../client-server/definitions/room_summary.yaml
72+
- type: object
73+
properties:
74+
membership:
75+
description: |-
76+
The membership state of the user if the user is joined to the room. Absent
77+
if the API was called unauthenticated.
78+
enum:
79+
- invite
80+
- join
81+
- knock
82+
- leave
83+
- ban
84+
type: string
85+
required:
86+
- guest_can_join
87+
- num_joined_members
88+
- room_id
89+
- world_readable
90+
examples:
91+
response:
92+
value: {
93+
room_id: "!ol19s:bleecker.street",
94+
avatar_url: "mxc://bleecker.street/CHEDDARandBRIE",
95+
guest_can_join: false,
96+
name: "CHEESE",
97+
num_joined_members: 37,
98+
topic: "Tasty tasty cheese",
99+
world_readable: true,
100+
join_rule: "public",
101+
room_type: "m.space",
102+
membership: "invite",
103+
encryption: "m.megolm.v1.aes-sha2",
104+
room_version: "9001",
105+
}
106+
"404":
107+
description: |-
108+
The room could not be found.
109+
content:
110+
application/json:
111+
schema:
112+
$ref: ../client-server/definitions/errors/error.yaml
113+
examples:
114+
response:
115+
value: {
116+
"errcode": "M_NOT_FOUND",
117+
"error": "Room not found."
118+
}
119+
servers:
120+
- url: "{protocol}://{hostname}{basePath}"
121+
variables:
122+
protocol:
123+
enum:
124+
- http
125+
- https
126+
default: https
127+
hostname:
128+
default: localhost:8008
129+
basePath:
130+
default: /_matrix/client/v1
131+
components:
132+
securitySchemes:
133+
accessTokenQuery:
134+
$ref: definitions/security.yaml#/accessTokenQuery
135+
accessTokenBearer:
136+
$ref: definitions/security.yaml#/accessTokenBearer

‎data/api/client-server/space_hierarchy.yaml‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -102,15 +102,10 @@ paths:
102102
* The room's [`m.room.history_visibility`](#room-history-visibility) is set to `world_readable`.
103103
items:
104104
allOf:
105-
- $ref: definitions/public_rooms_chunk.yaml
105+
- $ref: definitions/room_summary.yaml
106106
- type: object
107107
title: SpaceHierarchyRoomsChunk
108108
properties:
109-
room_type:
110-
type: string
111-
description: The `type` of room (from
112-
[`m.room.create`](/client-server-api/#mroomcreate)),
113-
if any.
114109
children_state:
115110
type: array
116111
description: |-
@@ -130,6 +125,14 @@ paths:
130125
description: The `origin_server_ts` for the event.
131126
required:
132127
- origin_server_ts
128+
room_type:
129+
x-addedInMatrixVersion: "1.4" # Extends room_summary.yaml
130+
allowed_room_ids:
131+
x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
132+
encryption:
133+
x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
134+
room_version:
135+
x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
133136
required:
134137
- children_state
135138
next_batch:

‎data/api/server-server/space_hierarchy.yaml‎

Lines changed: 13 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -61,22 +61,10 @@ paths:
6161
room:
6262
description: A summary of the room requested.
6363
allOf:
64-
- $ref: ../client-server/definitions/public_rooms_chunk.yaml
64+
- $ref: ../client-server/definitions/room_summary.yaml
6565
- type: object
6666
title: SpaceHierarchyParentRoom
6767
properties:
68-
room_type:
69-
type: string
70-
description: The `type` of room (from
71-
[`m.room.create`](/client-server-api/#mroomcreate)),
72-
if any.
73-
allowed_room_ids:
74-
type: array
75-
items:
76-
type: string
77-
description: |-
78-
If the room is a [restricted room](/server-server-api/#restricted-rooms), these are the room IDs which
79-
are specified by the join rules. Empty or omitted otherwise.
8068
children_state:
8169
type: array
8270
description: |-
@@ -96,6 +84,12 @@ paths:
9684
description: The `origin_server_ts` for the event.
9785
required:
9886
- origin_server_ts
87+
room_type:
88+
x-addedInMatrixVersion: "1.4" # Extends room_summary.yaml
89+
encryption:
90+
x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
91+
room_version:
92+
x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
9993
required:
10094
- children_state
10195
children:
@@ -105,22 +99,16 @@ paths:
10599
be excluded.
106100
items:
107101
allOf:
108-
- $ref: ../client-server/definitions/public_rooms_chunk.yaml
102+
- $ref: ../client-server/definitions/room_summary.yaml
109103
- type: object
110104
title: SpaceHierarchyChildRoomsChunk
111105
properties:
112106
room_type:
113-
type: string
114-
description: The `type` of room (from
115-
[`m.room.create`](/client-server-api/#mroomcreate)),
116-
if any.
117-
allowed_room_ids:
118-
type: array
119-
items:
120-
type: string
121-
description: |-
122-
If the room is a [restricted room](/server-server-api/#restricted-rooms), these are the room IDs which
123-
are specified by the join rules. Empty or omitted otherwise.
107+
x-addedInMatrixVersion: "1.4" # Extends room_summary.yaml
108+
encryption:
109+
x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
110+
room_version:
111+
x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
124112
inaccessible_children:
125113
type: array
126114
items:

0 commit comments

Comments
 (0)