06b0c1762a
Both APIs need clarification, so dedupe the changes. We should also probably deprecate some of this stuff so we can eventually remove it.
274 lines
9.8 KiB
YAML
274 lines
9.8 KiB
YAML
# 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`_ handshake. Note that
|
|
events have a different format depending on the room version - check the
|
|
`room version specification`_ 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`_
|
|
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"
|
|
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"
|
|
}
|
|
}
|
|
}
|
|
400:
|
|
description: |-
|
|
The request is invalid or the room the server is attempting
|
|
to join has a version that is not listed in the ``ver``
|
|
parameters.
|
|
|
|
The error should be passed through to clients so that they
|
|
may give better feedback to users.
|
|
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"
|
|
}
|
|
"/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`_ 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"
|
|
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"
|
|
}
|
|
}
|
|
responses:
|
|
200:
|
|
description: |-
|
|
The full state for the room, having accepted the join event.
|
|
schema:
|
|
type: array
|
|
minItems: 2
|
|
maxItems: 2
|
|
items:
|
|
- type: integer
|
|
description: The value ``200``.
|
|
example: 200
|
|
- $ref: "./definitions/send_join_response.yaml"
|
|
examples:
|
|
application/json: [
|
|
200,
|
|
{
|
|
"origin": "matrix.org",
|
|
"auth_chain": [{"$ref": "examples/minimal_pdu.json"}],
|
|
"state": [{"$ref": "examples/minimal_pdu.json"}]
|
|
}
|
|
]
|