Skip to content

Commit 45fbfab

Browse files
richvdhrichvdh
committed
Clarify resposnse documentation.
1 parent 6aacb77 commit 45fbfab

File tree

1 file changed

+49
-36
lines changed

1 file changed

+49
-36
lines changed

‎proposals/3266-room-summary.md

+49-36
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ GET /_matrix/client/v1/room_summary/{roomIdOrAlias}?
5959
be generated locally. These can be from a matrix URI, matrix.to link or a
6060
`m.space.child` event for example.
6161

62-
A successful `200` response includes the stripped state in the following format:
62+
A successful `200` response should contain a JSON object giving information about the room. For example:
6363

6464
```json5
6565
{
@@ -78,18 +78,7 @@ A successful `200` response includes the stripped state in the following format:
7878
}
7979
```
8080

81-
These are the same fields as those returned by [`/publicRooms`](https://spec.matrix.org/v1.13/client-server-api/#get_matrixclientv3publicrooms) or
82-
[`/hierarchy`](https://spec.matrix.org/v1.13/client-server-api/#get_matrixclientv1roomsroomidhierarchy)
83-
, with a few additions: `membership`, `room_version`,
84-
`encryption` and `allowed_room_ids`.
85-
86-
`room_version` and `encryption` are already accessible as part of
87-
the stripped state according to
88-
https://spec.matrix.org/v1.13/client-server-api/#stripped-state . The
89-
`membership` is not, but a client could access that in various different ways
90-
already. This API just makes this more convenient.
91-
`allowed_room_ids` is already part of the federation `hierarchy` API and
92-
necessary for distinguishing possible join modes for `knock_restricted` rooms.
81+
See below for a more detailed description of the response.
9382

9483
#### Unauthenticated and guest access
9584

@@ -108,42 +97,66 @@ user is unauthenticated.
10897
When the endpoint is called unauthenticated, the `membership` field will be
10998
absent in the response.
11099

111-
#### Rationale and description of response fields
112-
113-
| fieldname | description | rationale |
114-
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
115-
| room_id | Required. Id of the room | Useful when the API is called with an alias. |
116-
| avatar_url | Optional. Avatar of the room | Copied from `publicRooms`. |
117-
| canonical_alias | Optional. The canonical alias of the room, if any. | Copied from `publicRooms`. |
118-
| guest_can_join | Required. If guests can join the room. | Copied from `publicRooms`. |
119-
| name | Optional. Name of the room | Copied from `publicRooms`. |
120-
| num_joined_members | Required. Member count of the room | Copied from `publicRooms`. |
121-
| topic | Optional. Topic of the room | Copied from `publicRooms`. |
122-
| world_readable | Required. If the room history can be read without joining. | Copied from `publicRooms`. |
123-
| join_rule | Optional. Join rules of the room | Copied from `publicRooms`. |
124-
| allowed_room_ids | Optional. Room ids allows in restricted joins. | Copied from [`GET /_matrix/federation/v1/hierarchy/{roomId}`](https://spec.matrix.org/v1.13/server-server-api/#get_matrixfederationv1hierarchyroomid). Necessary to distinguish if the room can be joined or only knocked at. |
125-
| room_type | Optional. Type of the room, if any, i.e. `m.space` | Used to distinguish rooms from spaces. |
126-
| room_version | Optional (for historical reasons (2)). Version of the room. | Can be used by clients to show incompatibilities with a room early. |
127-
| membership | Optional (1). The current membership of this user in the room. Usually `leave` if the room is fetched over federation. | Useful to distinguish invites and knocks from joined rooms. |
128-
| encryption | Optional. If the room is encrypted this specified the algorithm used for this room. This is already accessible as stripped state. | Some users may only want to join encrypted rooms or clients may want to filter out encrypted rooms, if they don't support encryption or not this algorithm. |
129-
130-
100+
#### Response format
131101

132102
If the room cannot be found, the server should return a `404`
133103
HTTP status code along with an `M_NOT_FOUND` error code. The server should
134104
NOT return `M_UNAUTHORIZED` or otherwise divulge existence of a room, that
135105
requires authentication to preview, if the request is unauthenticated or
136106
authenticated by a user without access to the room.
137107

108+
If the request is successful, the server returns a JSON object containing the
109+
following properties:
110+
111+
| property name | description |
112+
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
113+
| avatar_url | Optional. Avatar of the room |
114+
| canonical_alias | Optional. The canonical alias of the room, if any. |
115+
| guest_can_join | Required. Whether guests can join the room. |
116+
| join_rule | Optional. Join rules of the room |
117+
| name | Optional. Name of the room |
118+
| num_joined_members | Required. Member count of the room |
119+
| room_id | Required. Id of the room |
120+
| room_type | Optional. Type of the room, if any, i.e. `m.space` |
121+
| topic | Optional. Topic of the room |
122+
| world_readable | Required. If the room history can be read without joining. |
123+
| allowed_room_ids | Optional. If the room is a restricted room, these are the room IDs which are specified by the join rules. Empty or omitted otherwise. |
124+
| encryption | Optional. If the room is encrypted, this specifies the algorithm used for this room. Otherwise, omitted. |
125+
| membership | Optional (1). The current membership of this user in the room. Usually `leave` if the server has no local users (so fetches the room over federation). |
126+
| room_version | Optional (for historical reasons (2)). Version of the room. |
127+
138128
(1) The `membership` field will not be present when called unauthenticated, but
139-
is required when called authenticated. It should be `leave` if the server
140-
doesn't know about the room, since for all other membership states the server
141-
would know about the room already.
129+
is required when called authenticated.
142130

143131
(2) Prior to this MSC, `/_matrix/federation/v1/hierarchy/{roomId}` doesn't
144132
return the room version, so `room_version` may be unavailable for remote
145133
rooms.
146134

135+
Most of the fields above are the same as those returned by
136+
[`/_matrix/client/v3/publicRooms`](https://spec.matrix.org/v1.13/client-server-api/#get_matrixclientv3publicrooms). (Those
137+
same fields are also a subset of those returned by
138+
[`/_matrix/client/v1/rooms/{roomId}/hierarchy`](https://spec.matrix.org/v1.13/client-server-api/#get_matrixclientv1roomsroomidhierarchy).) The
139+
exceptions are:
140+
141+
* `allowed_room_ids`. This is currently accessible via the federation
142+
hierarchy endpoint [`GET
143+
/_matrix/federation/v1/hierarchy/{roomId}`](https://spec.matrix.org/v1.13/server-server-api/#get_matrixfederationv1hierarchyroomid),
144+
and is necessary
145+
to distinguish if the room can be joined or only knocked at.
146+
147+
* `encryption`. Currently part of the [stripped
148+
state](https://spec.matrix.org/v1.13/client-server-api/#stripped-state). Some
149+
users may only want to join encrypted rooms; alternatively, clients may want to filter
150+
out encrypted rooms, for example if they don't support encryption, or do not
151+
support particular encryption algorithms.
152+
153+
* `membership`. Exposed solely for convenience: a client has many other ways
154+
to access this information.
155+
156+
* `room_version`. Also part of the [stripped
157+
state](https://spec.matrix.org/v1.13/client-server-api/#stripped-state).
158+
Can be used by clients to show incompatibilities with a room early.
159+
147160
#### Modifications to `/_matrix/client/v1/rooms/{roomId}/hierarchy`
148161

149162
For symmetry the `room_version`, `allowed_room_ids` and `encryption` fields are

0 commit comments

Comments
 (0)