3adbfa30da
We used to only look for examples in a few (sometimes arbitrary) places, and we didn't support showing several examples in most cases. This is intended to fix this. In the process we try to deduplicate code to make sure that we use the same logic everywhere. Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
354 lines
13 KiB
YAML
354 lines
13 KiB
YAML
# Copyright 2021 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 Federation Knock Room API
|
|
version: 1.0.0
|
|
paths:
|
|
"/make_knock/{roomId}/{userId}":
|
|
get:
|
|
x-addedInMatrixVersion: "1.1"
|
|
summary: Get information required to make a knock event for a room.
|
|
description: |-
|
|
Asks the receiving server to return information that the sending
|
|
server will need to prepare a knock event for the room.
|
|
operationId: makeKnock
|
|
security:
|
|
- signedRequest: []
|
|
parameters:
|
|
- in: path
|
|
name: roomId
|
|
description: The room ID that is about to be knocked.
|
|
required: true
|
|
example: "!abc123:example.org"
|
|
schema:
|
|
type: string
|
|
- in: path
|
|
name: userId
|
|
description: The user ID the knock event will be for.
|
|
required: true
|
|
example: "@someone:example.org"
|
|
schema:
|
|
type: string
|
|
- in: query
|
|
name: ver
|
|
description: The room versions the sending server has support for.
|
|
required: true # knocking was supported in v7
|
|
example:
|
|
- "1"
|
|
- "7"
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: |-
|
|
A template to be used for the rest of the [Knocking Rooms](/server-server-api/#knocking-rooms)
|
|
handshake. Note that events have a different format depending on 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.**
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
room_version:
|
|
type: string
|
|
description: The version of the room where the server is trying to knock.
|
|
example: "7"
|
|
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 knocking 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 knocking member.
|
|
example: "@someone:example.org"
|
|
content:
|
|
type: object
|
|
title: Membership Event Content
|
|
description: The content of the event.
|
|
example:
|
|
membership: knock
|
|
properties:
|
|
membership:
|
|
type: string
|
|
description: The value `knock`.
|
|
example: knock
|
|
required:
|
|
- membership
|
|
required:
|
|
- state_key
|
|
- origin
|
|
- origin_server_ts
|
|
- type
|
|
- content
|
|
- sender
|
|
required:
|
|
- room_version # knocking was added in v7
|
|
- event
|
|
examples:
|
|
response:
|
|
value: {
|
|
"room_version": "7",
|
|
"event": {
|
|
"room_id": "!somewhere:example.org",
|
|
"type": "m.room.member",
|
|
"state_key": "@someone:example.org",
|
|
"origin": "example.org",
|
|
"origin_server_ts": 1549041175876,
|
|
"sender": "@someone:example.org",
|
|
"content": {
|
|
"membership": "knock"
|
|
}
|
|
}
|
|
}
|
|
"400":
|
|
description: |-
|
|
The request is invalid or the room the server is attempting
|
|
to knock upon 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.
|
|
content:
|
|
application/json:
|
|
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:
|
|
response:
|
|
value: {
|
|
"errcode": "M_INCOMPATIBLE_ROOM_VERSION",
|
|
"error": "Your homeserver does not support the features required to knock on this room",
|
|
"room_version": "7"
|
|
}
|
|
"403":
|
|
description: |-
|
|
The knocking server or user is not permitted to knock on the room, such as when the
|
|
server/user is banned or the room is not set up for receiving knocks.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: ../client-server/definitions/errors/error.yaml
|
|
examples:
|
|
response:
|
|
value: {
|
|
"errcode": "M_FORBIDDEN",
|
|
"error": "You are not permitted to knock on this room"
|
|
}
|
|
"404":
|
|
description: |-
|
|
The room that the knocking server is attempting to knock upon is unknown
|
|
to the receiving server.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: ../client-server/definitions/errors/error.yaml
|
|
examples:
|
|
response:
|
|
value: {
|
|
"errcode": "M_NOT_FOUND",
|
|
"error": "Unknown room"
|
|
}
|
|
"/send_knock/{roomId}/{eventId}":
|
|
put:
|
|
x-addedInMatrixVersion: "1.1"
|
|
summary: Submit a signed knock event to a resident server.
|
|
description: |-
|
|
Submits a signed knock event to the resident server for it to
|
|
accept 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: sendKnock
|
|
security:
|
|
- signedRequest: []
|
|
parameters:
|
|
- in: path
|
|
name: roomId
|
|
description: The room ID that is about to be knocked upon.
|
|
required: true
|
|
example: "!abc123:example.org"
|
|
schema:
|
|
type: string
|
|
- in: path
|
|
name: eventId
|
|
description: The event ID for the knock event.
|
|
required: true
|
|
example: $abc123:example.org
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
sender:
|
|
type: string
|
|
description: The user ID of the knocking member.
|
|
example: "@someone:example.org"
|
|
origin:
|
|
type: string
|
|
description: The name of the knocking homeserver.
|
|
example: matrix.org
|
|
origin_server_ts:
|
|
type: integer
|
|
format: int64
|
|
description: A timestamp added by the knocking 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 knocking member.
|
|
example: "@someone:example.org"
|
|
content:
|
|
type: object
|
|
title: Membership Event Content
|
|
description: The content of the event.
|
|
example:
|
|
membership: knock
|
|
properties:
|
|
membership:
|
|
type: string
|
|
description: The value `knock`.
|
|
example: knock
|
|
required:
|
|
- membership
|
|
required:
|
|
- state_key
|
|
- sender
|
|
- origin
|
|
- origin_server_ts
|
|
- type
|
|
- content
|
|
example: {
|
|
"type": "m.room.member",
|
|
"state_key": "@someone:example.org",
|
|
"origin": "example.org",
|
|
"origin_server_ts": 1549041175876,
|
|
"sender": "@someone:example.org",
|
|
"content": {
|
|
"membership": "knock"
|
|
}
|
|
}
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: |-
|
|
Information about the room to pass along to clients regarding the
|
|
knock.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
knock_room_state:
|
|
type: array
|
|
items:
|
|
$ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
|
|
description: |-
|
|
A list of [stripped state events](/client-server-api/#stripped-state)
|
|
to help the initiator of the knock identify the room.
|
|
example:
|
|
$ref: ../../event-schemas/examples/knock_room_state.json
|
|
required:
|
|
- knock_room_state
|
|
examples:
|
|
response:
|
|
value: {
|
|
"knock_room_state": {
|
|
"$ref": "../../event-schemas/examples/knock_room_state.json"
|
|
}
|
|
}
|
|
"403":
|
|
description: |-
|
|
The knocking server or user is not permitted to knock on the room, such as when the
|
|
server/user is banned or the room is not set up for receiving knocks.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: ../client-server/definitions/errors/error.yaml
|
|
examples:
|
|
response:
|
|
value: {
|
|
"errcode": "M_FORBIDDEN",
|
|
"error": "You are not permitted to knock on this room"
|
|
}
|
|
"404":
|
|
description: |-
|
|
The room that the knocking server is attempting to knock upon is unknown
|
|
to the receiving server.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: ../client-server/definitions/errors/error.yaml
|
|
examples:
|
|
response:
|
|
value: {
|
|
"errcode": "M_NOT_FOUND",
|
|
"error": "Unknown room"
|
|
}
|
|
servers:
|
|
- url: "{protocol}://{hostname}{basePath}"
|
|
variables:
|
|
protocol:
|
|
enum:
|
|
- http
|
|
- https
|
|
default: https
|
|
hostname:
|
|
default: localhost:8448
|
|
basePath:
|
|
default: /_matrix/federation/v1
|
|
components:
|
|
securitySchemes:
|
|
signedRequest:
|
|
$ref: definitions/security.yaml#/signedRequest
|