-
-
Notifications
You must be signed in to change notification settings - Fork 89
/
joins-v1.yaml
385 lines (373 loc) · 15.5 KB
/
joins-v1.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
# Copyright 2018 New Vector Ltd
# Copyright 2020 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.
swagger: '2.0'
info:
title: "Matrix Federation Join Room API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/make_join/{roomId}/{userId}":
get:
summary: Get information required to make a join event for a room
description: |-
Asks the receiving server to return information that the sending
server will need to prepare a join event to get into the room.
operationId: makeJoin
security:
- signedRequest: []
parameters:
- in: path
name: roomId
type: string
description: The room ID that is about to be joined.
required: true
x-example: "!abc123:matrix.org"
- in: path
name: userId
type: string
description: The user ID the join event will be for.
required: true
x-example: "@someone:example.org"
- in: query
type: array
items:
type: string
name: ver
description: |-
The room versions the sending server has support for. Defaults
to `[1]`.
x-example: ["1", "2"]
responses:
200:
description: |-
A template to be used for the rest of the [Joining Rooms](/server-server-api/#joining-rooms) handshake. Note that
events have a different format depending on the room version - check the
[room version specification](/rooms) for precise event formats. **The response body
here describes the common event fields in more detail and may be missing other
required fields for a PDU.**
schema:
type: object
properties:
room_version:
type: string
description: |-
The version of the room where the server is trying to join. If not provided,
the room version is assumed to be either "1" or "2".
example: "2"
event:
description: |-
An unsigned template event. Note that events have a different format
depending on the room version - check the [room version specification](/rooms)
for precise event formats.
type: object
title: Event Template
properties:
sender:
type: string
description: The user ID of the joining member.
example: "@someone:example.org"
origin:
type: string
description: The name of the resident homeserver.
example: "matrix.org"
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the resident homeserver.
example: 1234567890
type:
type: string
description: The value `m.room.member`.
example: "m.room.member"
state_key:
type: string
description: The user ID of the joining member.
example: "@someone:example.org"
content:
type: object
title: Membership Event Content
description: The content of the event.
example: {"membership": "join"}
properties:
membership:
type: string
description: The value `join`.
example: "join"
join_authorised_via_users_server:
type: string
x-addedInMatrixVersion: "1.2"
description: |-
Required if the room is [restricted](/client-server-api/#restricted-rooms)
and is joining through one of the conditions available. If the
user is responding to an invite, this is not required.
An arbitrary user ID belonging to the resident server in
the room being joined that is able to issue invites to other
users. This is used in later validation of the auth rules for
the `m.room.member` event.
required: ['membership']
required:
- state_key
- origin
- origin_server_ts
- type
- content
- sender
examples:
application/json: {
"room_version": "2",
"event": {
"$ref": "examples/minimal_pdu.json",
"type": "m.room.member",
"state_key": "@someone:example.org",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"content": {
"membership": "join",
"join_authorised_via_users_server": "@anyone:resident.example.org"
}
}
}
400:
description: |-
The request is invalid, the room the server is attempting
to join has a version that is not listed in the `ver`
parameters, or the server was unable to validate
[restricted room conditions](#restricted-rooms).
The error should be passed through to clients so that they
may give better feedback to users.
New in `v1.2`, the following error conditions might happen:
If the room is [restricted](/client-server-api/#restricted-rooms)
and none of the conditions can be validated by the server then
the `errcode` `M_UNABLE_TO_AUTHORISE_JOIN` must be used. This can
happen if the server does not know about any of the rooms listed
as conditions, for example.
`M_UNABLE_TO_GRANT_JOIN` is returned to denote that a different
server should be attempted for the join. This is typically because
the resident server can see that the joining user satisfies one or
more conditions, such as in the case of
[restricted rooms](/client-server-api/#restricted-rooms), but the
resident server would be unable to meet the auth rules governing
`join_authorised_via_users_server` on the resulting `m.room.member`
event.
schema:
allOf:
- $ref: "../client-server/definitions/errors/error.yaml"
- type: object
properties:
room_version:
type: string
description: |-
The version of the room. Required if the `errcode`
is `M_INCOMPATIBLE_ROOM_VERSION`.
examples:
application/json: {
"errcode": "M_INCOMPATIBLE_ROOM_VERSION",
"error": "Your homeserver does not support the features required to join this room",
"room_version": "3"
}
403:
schema:
$ref: "../client-server/definitions/errors/error.yaml"
description: |-
The room that the joining server is attempting to join does not permit the user
to join.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You are not invited to this room",
}
404:
schema:
$ref: "../client-server/definitions/errors/error.yaml"
description: |-
The room that the joining server is attempting to join is unknown
to the receiving server.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Unknown room",
}
"/send_join/{roomId}/{eventId}":
put:
summary: Submit a signed join event to a resident server
description: |-
**Note:**
Servers should instead prefer to use the v2 `/send_join` endpoint.
Submits a signed join event to the resident server for it
to accept it into the room's graph. Note that events have
a different format depending on the room version - check
the [room version specification](/rooms) for precise event formats.
**The request and response body here describe the common
event fields in more detail and may be missing other required
fields for a PDU.**
operationId: sendJoinV1
security:
- signedRequest: []
parameters:
- in: path
name: roomId
type: string
description: The room ID that is about to be joined.
required: true
x-example: "!abc123:matrix.org"
- in: path
name: eventId
type: string
description: The event ID for the join event.
required: true
x-example: "$abc123:example.org"
- in: body
name: body
type: object
required: true
schema:
type: object
properties:
sender:
type: string
description: The user ID of the joining member.
example: "@someone:example.org"
origin:
type: string
description: The name of the joining homeserver.
example: "matrix.org"
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the joining homeserver.
example: 1234567890
type:
type: string
description: The value `m.room.member`.
example: "m.room.member"
state_key:
type: string
description: The user ID of the joining member.
example: "@someone:example.org"
content:
type: object
title: Membership Event Content
description: The content of the event.
example: {"membership": "join"}
properties:
membership:
type: string
description: The value `join`.
example: "join"
join_authorised_via_users_server:
type: string
x-addedInMatrixVersion: "1.2"
description: |-
Required if the room is [restricted](/client-server-api/#restricted-rooms)
and is joining through one of the conditions available. If the
user is responding to an invite, this is not required.
An arbitrary user ID belonging to the resident server in
the room being joined that is able to issue invites to other
users. This is used in later validation of the auth rules for
the `m.room.member` event.
The resident server which owns the provided user ID must have a
valid signature on the event. If the resident server is receiving
the `/send_join` request, the signature must be added before sending
or persisting the event to other servers.
required: ['membership']
required:
- state_key
- sender
- origin
- origin_server_ts
- type
- content
example: {
"$ref": "examples/minimal_pdu.json",
"type": "m.room.member",
"state_key": "@someone:example.org",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"content": {
"membership": "join",
"join_authorised_via_users_server": "@anyone:resident.example.org"
}
}
responses:
200:
description: |-
The join event has been accepted into the room.
schema:
type: array
minItems: 2
maxItems: 2
items:
- type: integer
description: The value `200`.
example: 200
- type: object
title: Room State
description: The state for the room.
properties:
origin:
type: string
description: The resident server's DNS name.
auth_chain:
type: array
description: |-
The auth chain for the entire current room state prior to the join event.
Note that events have a different format depending on the room version - check the
[room version specification](/rooms) for precise event formats.
items:
type: object
title: PDU
description: |-
The [PDUs](/server-server-api/#pdus) that make up the auth chain. The event format varies depending
on the room version - check the [room version specification](/rooms) for precise event formats.
schema:
type: object
properties: {}
state:
type: array
description: |-
The resolved current room state prior to the join event.
The event format varies depending on the room version - check the [room version specification](/rooms)
for precise event formats.
items:
type: object
title: PDU
description: |-
The [PDUs](/server-server-api/#pdus) for the fully resolved state of the room. The event format varies depending
on the room version - check the [room version specification](/rooms) for precise event formats.
schema:
type: object
properties: {}
required: ["auth_chain", "state", "origin"]
examples:
application/json: [
200,
{
"origin": "matrix.org",
"auth_chain": [{"$ref": "examples/minimal_pdu.json"}],
"state": [{"$ref": "examples/minimal_pdu.json"}],
"event": {"$ref": "examples/pdu_v4_join_membership.json"}
}
]