Spec PR - MSC3266: Room Summary API (#2125)
Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>pull/2158/head
Johannes Marbach
6 months ago
committed by
GitHub
parent
866c05f487
commit
7bcc3ecb81
@ -0,0 +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).
|
||||||
@ -0,0 +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).
|
||||||
@ -0,0 +1,48 @@
|
|||||||
|
# Copyright 2025 The Matrix.org Foundation C.I.C.
|
||||||
|
#
|
||||||
|
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||||
|
# you may not use this file except in compliance with the License.
|
||||||
|
# You may obtain a copy of the License at
|
||||||
|
#
|
||||||
|
# http://www.apache.org/licenses/LICENSE-2.0
|
||||||
|
#
|
||||||
|
# Unless required by applicable law or agreed to in writing, software
|
||||||
|
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||||
|
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||||
|
# See the License for the specific language governing permissions and
|
||||||
|
# limitations under the License.
|
||||||
|
|
||||||
|
type: object
|
||||||
|
title: RoomSummary
|
||||||
|
allOf:
|
||||||
|
- $ref: public_rooms_chunk.yaml
|
||||||
|
- type: object
|
||||||
|
properties:
|
||||||
|
room_type:
|
||||||
|
type: string
|
||||||
|
description: The `type` of room (from
|
||||||
|
[`m.room.create`](/client-server-api/#mroomcreate)),
|
||||||
|
if any.
|
||||||
|
allowed_room_ids:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
If the room is a [restricted room](/server-server-api/#restricted-rooms), these are the room IDs which
|
||||||
|
are specified by the join rules. Empty or omitted otherwise.
|
||||||
|
encryption:
|
||||||
|
type: string
|
||||||
|
enum:
|
||||||
|
- "m.megolm.v1.aes-sha2"
|
||||||
|
description: |-
|
||||||
|
The encryption algorithm to be used to encrypt messages sent in the
|
||||||
|
room.
|
||||||
|
room_version:
|
||||||
|
description: The version of the room.
|
||||||
|
type: string
|
||||||
|
|
||||||
|
required:
|
||||||
|
- room_id
|
||||||
|
- num_joined_members
|
||||||
|
- world_readable
|
||||||
|
- guest_can_join
|
||||||
@ -0,0 +1,136 @@
|
|||||||
|
# Copyright 2025 The Matrix.org Foundation C.I.C.
|
||||||
|
#
|
||||||
|
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||||
|
# you may not use this file except in compliance with the License.
|
||||||
|
# You may obtain a copy of the License at
|
||||||
|
#
|
||||||
|
# http://www.apache.org/licenses/LICENSE-2.0
|
||||||
|
#
|
||||||
|
# Unless required by applicable law or agreed to in writing, software
|
||||||
|
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||||
|
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||||
|
# See the License for the specific language governing permissions and
|
||||||
|
# limitations under the License.
|
||||||
|
openapi: 3.1.0
|
||||||
|
info:
|
||||||
|
title: Matrix Client-Server Room Summary API
|
||||||
|
version: 1.0.0
|
||||||
|
paths:
|
||||||
|
"/room_summary/{roomIdOrAlias}":
|
||||||
|
get:
|
||||||
|
x-addedInMatrixVersion: "1.15"
|
||||||
|
summary: Retrieves a summary for a room.
|
||||||
|
description: |-
|
||||||
|
Retrieves a summary for a room.
|
||||||
|
|
||||||
|
Clients should note that requests for rooms where the user's membership
|
||||||
|
is `invite` or `knock` might yield outdated, partial or even no data
|
||||||
|
since the server may not have access to the current state of the room.
|
||||||
|
|
||||||
|
Servers MAY allow unauthenticated access to this API if at least one of
|
||||||
|
the following conditions holds true:
|
||||||
|
|
||||||
|
- The room has a [join rule](#mroomjoin_rules) of `public`, `knock` or
|
||||||
|
`knock_restricted`.
|
||||||
|
- The room has a `world_readable` [history visibility](#room-history-visibility).
|
||||||
|
|
||||||
|
Servers should consider rate limiting requests that require a federation
|
||||||
|
request more heavily if the client is unauthenticated.
|
||||||
|
operationId: getRoomSummary
|
||||||
|
security:
|
||||||
|
- signedRequest: []
|
||||||
|
parameters:
|
||||||
|
- in: path
|
||||||
|
name: roomIdOrAlias
|
||||||
|
description: The room identifier or alias to summarise.
|
||||||
|
required: true
|
||||||
|
example: "#monkeys:matrix.org"
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
- in: query
|
||||||
|
name: via
|
||||||
|
description: |-
|
||||||
|
The servers to attempt to request the summary from when
|
||||||
|
the local server cannot generate it (for instance, because
|
||||||
|
it has no local user in the room).
|
||||||
|
example:
|
||||||
|
- matrix.org
|
||||||
|
- elsewhere.ca
|
||||||
|
schema:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
responses:
|
||||||
|
"200":
|
||||||
|
description: A summary of the room.
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
description: A summary of the room.
|
||||||
|
allOf:
|
||||||
|
- $ref: ../client-server/definitions/room_summary.yaml
|
||||||
|
- type: object
|
||||||
|
properties:
|
||||||
|
membership:
|
||||||
|
description: |-
|
||||||
|
The membership state of the user if the user is joined to the room. Absent
|
||||||
|
if the API was called unauthenticated.
|
||||||
|
enum:
|
||||||
|
- invite
|
||||||
|
- join
|
||||||
|
- knock
|
||||||
|
- leave
|
||||||
|
- ban
|
||||||
|
type: string
|
||||||
|
required:
|
||||||
|
- guest_can_join
|
||||||
|
- num_joined_members
|
||||||
|
- room_id
|
||||||
|
- world_readable
|
||||||
|
examples:
|
||||||
|
response:
|
||||||
|
value: {
|
||||||
|
room_id: "!ol19s:bleecker.street",
|
||||||
|
avatar_url: "mxc://bleecker.street/CHEDDARandBRIE",
|
||||||
|
guest_can_join: false,
|
||||||
|
name: "CHEESE",
|
||||||
|
num_joined_members: 37,
|
||||||
|
topic: "Tasty tasty cheese",
|
||||||
|
world_readable: true,
|
||||||
|
join_rule: "public",
|
||||||
|
room_type: "m.space",
|
||||||
|
membership: "invite",
|
||||||
|
encryption: "m.megolm.v1.aes-sha2",
|
||||||
|
room_version: "9001",
|
||||||
|
}
|
||||||
|
"404":
|
||||||
|
description: |-
|
||||||
|
The room could not be found.
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: ../client-server/definitions/errors/error.yaml
|
||||||
|
examples:
|
||||||
|
response:
|
||||||
|
value: {
|
||||||
|
"errcode": "M_NOT_FOUND",
|
||||||
|
"error": "Room not found."
|
||||||
|
}
|
||||||
|
servers:
|
||||||
|
- url: "{protocol}://{hostname}{basePath}"
|
||||||
|
variables:
|
||||||
|
protocol:
|
||||||
|
enum:
|
||||||
|
- http
|
||||||
|
- https
|
||||||
|
default: https
|
||||||
|
hostname:
|
||||||
|
default: localhost:8008
|
||||||
|
basePath:
|
||||||
|
default: /_matrix/client/v1
|
||||||
|
components:
|
||||||
|
securitySchemes:
|
||||||
|
accessTokenQuery:
|
||||||
|
$ref: definitions/security.yaml#/accessTokenQuery
|
||||||
|
accessTokenBearer:
|
||||||
|
$ref: definitions/security.yaml#/accessTokenBearer
|
||||||
Loading…
Reference in New Issue