27b4cdcc9e
I did a quick search of the "deprecated" word in the data folder and set the field where the description says that a property is deprecated. This does not change the rendering of the spec because the descriptions already talk about the deprecation, but it can be used by tools that rely on the OpenAPI definitions and JSON Schemas. Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
177 lines
6.2 KiB
YAML
177 lines
6.2 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 Client-Server Room Knocking API
|
|
version: 1.0.0
|
|
paths:
|
|
"/knock/{roomIdOrAlias}":
|
|
post:
|
|
x-addedInMatrixVersion: "1.1"
|
|
summary: Knock on a room, requesting permission to join.
|
|
description: |-
|
|
*Note that this API takes either a room ID or alias, unlike other membership APIs.*
|
|
|
|
This API "knocks" on the room to ask for permission to join, if the user
|
|
is allowed to knock on the room. Acceptance of the knock happens out of
|
|
band from this API, meaning that the client will have to watch for updates
|
|
regarding the acceptance/rejection of the knock.
|
|
|
|
If the room history settings allow, the user will still be able to see
|
|
history of the room while being in the "knock" state. The user will have
|
|
to accept the invitation to join the room (acceptance of knock) to see
|
|
messages reliably. See the `/join` endpoints for more information about
|
|
history visibility to the user.
|
|
|
|
The knock will appear as an entry in the response of the
|
|
[`/sync`](/client-server-api/#get_matrixclientv3sync) API.
|
|
operationId: knockRoom
|
|
security:
|
|
- accessTokenQuery: []
|
|
- accessTokenBearer: []
|
|
parameters:
|
|
- in: path
|
|
name: roomIdOrAlias
|
|
description: The room identifier or alias to knock upon.
|
|
required: true
|
|
example: "#monkeys:matrix.org"
|
|
schema:
|
|
type: string
|
|
- in: query
|
|
name: server_name
|
|
deprecated: true
|
|
x-changedInMatrixVersion:
|
|
"1.12": |-
|
|
This parameter has been deprecated in favour of `via` and will be removed in
|
|
a future version of the spec.
|
|
|
|
Clients SHOULD use `via` when the homeserver they're talking to supports it.
|
|
To do this, they MAY either detect server support through the supported spec
|
|
versions in [`/_matrix/client/versions`](/client-server-api/#get_matrixclientversions)
|
|
or always include both parameters with identical values.
|
|
|
|
Homeservers MUST ignore all `server_name` parameters if any `via` parameters
|
|
are supplied.
|
|
description: |-
|
|
The servers to attempt to knock on the room through. One of the servers
|
|
must be participating in the room.
|
|
example:
|
|
- matrix.org
|
|
- elsewhere.ca
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
- in: query
|
|
name: via
|
|
x-addedInMatrixVersion: "1.12"
|
|
description: |-
|
|
The servers to attempt to knock on the room through. One of the servers
|
|
must be participating in the room.
|
|
example:
|
|
- matrix.org
|
|
- elsewhere.ca
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
reason:
|
|
type: string
|
|
description: |-
|
|
Optional reason to be included as the `reason` on the subsequent
|
|
membership event.
|
|
example: Looking for support
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: |-
|
|
The room has been knocked upon.
|
|
|
|
The knocked room ID must be returned in the `room_id` field.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
room_id:
|
|
type: string
|
|
description: The knocked room ID.
|
|
required:
|
|
- room_id
|
|
examples:
|
|
response:
|
|
value: {
|
|
"room_id": "!d41d8cd:matrix.org"
|
|
}
|
|
"403":
|
|
description: |-
|
|
You do not have permission to knock on the room. A meaningful `errcode`
|
|
and description error text will be returned. Example reasons for rejection are:
|
|
|
|
- The room is not set up for knocking.
|
|
- The user has been banned from the room.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: definitions/errors/error.yaml
|
|
examples:
|
|
response:
|
|
value: {
|
|
"errcode": "M_FORBIDDEN",
|
|
"error": "You are not allowed to knock on this room."
|
|
}
|
|
"404":
|
|
description: The room could not be found or resolved to a room ID.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: definitions/errors/error.yaml
|
|
examples:
|
|
response:
|
|
value: {
|
|
"errcode": "M_NOT_FOUND",
|
|
"error": "That room does not appear to exist."
|
|
}
|
|
"429":
|
|
description: This request was rate-limited.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: definitions/errors/rate_limited.yaml
|
|
tags:
|
|
- Room membership
|
|
servers:
|
|
- url: "{protocol}://{hostname}{basePath}"
|
|
variables:
|
|
protocol:
|
|
enum:
|
|
- http
|
|
- https
|
|
default: https
|
|
hostname:
|
|
default: localhost:8008
|
|
basePath:
|
|
default: /_matrix/client/v3
|
|
components:
|
|
securitySchemes:
|
|
accessTokenQuery:
|
|
$ref: definitions/security.yaml#/accessTokenQuery
|
|
accessTokenBearer:
|
|
$ref: definitions/security.yaml#/accessTokenBearer
|