wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
docs-matrix-spec/data/api/client-server/joining.yaml
Kévin Commaille 27b4cdcc9e
Add the deprecated field to OpenAPI definitions and JSON Schemas (#1940) 
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>
2024-10-01 14:39:57 +01:00

263 lines
9.6 KiB
YAML
Raw Blame History

# Copyright 2016 OpenMarket Ltd
#
# 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 Inviting API
version: 1.0.0
paths:
"/rooms/{roomId}/join":
post:
summary: Start the requesting user participating in a particular room.
description: |-
*Note that this API requires a room ID, not alias.*
`/join/{roomIdOrAlias}` *exists if you have a room alias.*
This API starts a user participating in a particular room, if that user
is allowed to participate in that room. After this call, the client is
allowed to see all current state events in the room, and all subsequent
events associated with the room until the user leaves the room.
After a user has joined a room, the room will appear as an entry in the
response of the [`/initialSync`](/client-server-api/#get_matrixclientv3initialsync)
and [`/sync`](/client-server-api/#get_matrixclientv3sync) APIs.
operationId: joinRoomById
security:
- accessTokenQuery: []
- accessTokenBearer: []
parameters:
- in: path
name: roomId
description: The room identifier (not alias) to join.
required: true
example: "!d41d8cd:matrix.org"
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
third_party_signed:
allOf:
- $ref: definitions/third_party_signed.yaml
description: |-
If supplied, the homeserver must verify that it matches a pending
`m.room.third_party_invite` event in the room, and perform
key validity checking if required by the event.
reason:
x-addedInMatrixVersion: "1.1"
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 joined.
The joined room ID must be returned in the `room_id` field.
content:
application/json:
schema:
type: object
properties:
room_id:
type: string
description: The joined room ID.
required:
- room_id
examples:
response:
value: {
"room_id": "!d41d8cd:matrix.org"
}
"403":
description: |-
You do not have permission to join the room. A meaningful `errcode`
and description error text will be returned. Example reasons for rejection are:
- The room is invite-only and the user was not invited.
- The user has been banned from the room.
- The room is restricted and the user failed to satisfy any of the conditions.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "You are not invited to this room."
}
"429":
description: This request was rate-limited.
content:
application/json:
schema:
$ref: definitions/errors/rate_limited.yaml
tags:
- Room membership
"/join/{roomIdOrAlias}":
post:
summary: Start the requesting user participating in a particular room.
description: |-
*Note that this API takes either a room ID or alias, unlike* `/rooms/{roomId}/join`.
This API starts a user participating in a particular room, if that user
is allowed to participate in that room. After this call, the client is
allowed to see all current state events in the room, and all subsequent
events associated with the room until the user leaves the room.
After a user has joined a room, the room will appear as an entry in the
response of the [`/initialSync`](/client-server-api/#get_matrixclientv3initialsync)
and [`/sync`](/client-server-api/#get_matrixclientv3sync) APIs.
operationId: joinRoom
security:
- accessTokenQuery: []
- accessTokenBearer: []
parameters:
- in: path
name: roomIdOrAlias
description: The room identifier or alias to join.
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 join 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 join 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:
third_party_signed:
allOf:
- $ref: definitions/third_party_signed.yaml
description: |-
If a `third_party_signed` was supplied, the homeserver must verify
that it matches a pending `m.room.third_party_invite` event in the
room, and perform key validity checking if required by the event.
reason:
x-addedInMatrixVersion: "1.1"
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 joined.
The joined room ID must be returned in the `room_id` field.
content:
application/json:
schema:
type: object
properties:
room_id:
type: string
description: The joined room ID.
required:
- room_id
examples:
response:
value: {
"room_id": "!d41d8cd:matrix.org"
}
"403":
description: |-
You do not have permission to join the room. A meaningful `errcode`
and description error text will be returned. Example reasons for rejection are:
- The room is invite-only and the user was not invited.
- The user has been banned from the room.
- The room is restricted and the user failed to satisfy any of the conditions.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "You are not invited to this room."
}
"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
Reference in a new issue View git blame Copy permalink