mirror of
https://github.com/matrix-org/matrix-spec
synced 2025-12-24 18:08:37 +01:00
820704a16a
According the the openapi spec, examples for responses and schemas should be raw objects rather than being json strings. (It's unclear what non-json examples should look like...). The swagger UI used to support json strings, but no longer does. In short, let's turn the json strings into their raw formats.
213 lines
8.2 KiB
YAML
213 lines
8.2 KiB
YAML
# 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.
|
|
swagger: '2.0'
|
|
info:
|
|
title: "Matrix Client-Server Room Inviting API"
|
|
version: "1.0.0"
|
|
host: localhost:8008
|
|
schemes:
|
|
- https
|
|
- http
|
|
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
securityDefinitions:
|
|
$ref: definitions/security.yaml
|
|
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|_ and |/sync|_ APIs.
|
|
|
|
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.
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: path
|
|
type: string
|
|
name: roomId
|
|
description: The room identifier (not alias) to join.
|
|
required: true
|
|
x-example: "!d41d8cd:matrix.org"
|
|
- in: body
|
|
name: third_party_signed
|
|
schema:
|
|
type: object
|
|
example: {
|
|
"third_party_signed": {
|
|
"sender": "@cat:the.hat",
|
|
"mxid": "@green:eggs.ham",
|
|
"token": "random8nonce",
|
|
"signatures": {
|
|
"horton.hears": {
|
|
"ed25519:0": "some9signature"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
properties:
|
|
third_party_signed:
|
|
type: object
|
|
title: ThirdPartySigned
|
|
description: A signature of an ``m.third_party_invite`` token to prove that this user owns a third party identity which has been invited to the room.
|
|
properties:
|
|
sender:
|
|
type: string
|
|
description: The Matrix ID of the user who issued the invite.
|
|
mxid:
|
|
type: string
|
|
description: The Matrix ID of the invitee.
|
|
token:
|
|
type: string
|
|
description: The state key of the m.third_party_invite event.
|
|
signatures:
|
|
type: object
|
|
description: A signatures object containing a signature of the entire signed object.
|
|
title: Signatures
|
|
required: ["sender", "mxid", "token", "signatures"]
|
|
responses:
|
|
200:
|
|
description: |-
|
|
The room has been joined.
|
|
|
|
The joined room ID must be returned in the ``room_id`` field.
|
|
examples:
|
|
application/json: {
|
|
"room_id": "!d41d8cd:matrix.org"}
|
|
schema:
|
|
type: object
|
|
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.
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_FORBIDDEN", "error": "You are not invited to this room."}
|
|
429:
|
|
description: This request was rate-limited.
|
|
schema:
|
|
"$ref": "definitions/error.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* ``/room/{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|_ and |/sync|_ APIs.
|
|
|
|
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.
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: path
|
|
type: string
|
|
name: roomIdOrAlias
|
|
description: The room identifier or alias to join.
|
|
required: true
|
|
x-example: "#monkeys:matrix.org"
|
|
- in: body
|
|
name: third_party_signed
|
|
schema:
|
|
type: object
|
|
example: {
|
|
"third_party_signed": {
|
|
"signed": {
|
|
"sender": "@cat:the.hat",
|
|
"mxid": "@green:eggs.ham",
|
|
"token": "random8nonce",
|
|
"signatures": {
|
|
"horton.hears": {
|
|
"ed25519:0": "some9signature"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
properties:
|
|
third_party_signed:
|
|
type: object
|
|
title: ThirdPartySigned
|
|
description: A signature of an ``m.third_party_invite`` token to prove that this user owns a third party identity which has been invited to the room.
|
|
properties:
|
|
signed:
|
|
type: object
|
|
title: Signed
|
|
properties:
|
|
sender:
|
|
type: string
|
|
description: The Matrix ID of the user who issued the invite.
|
|
mxid:
|
|
type: string
|
|
description: The Matrix ID of the invitee.
|
|
token:
|
|
type: string
|
|
description: The state key of the m.third_party_invite event.
|
|
signatures:
|
|
type: object
|
|
description: A signatures object containing a signature of the entire signed object.
|
|
title: Signatures
|
|
required: ["sender", "mxid", "token", "signatures"]
|
|
required: ["signed"]
|
|
responses:
|
|
200:
|
|
description: |-
|
|
The room has been joined.
|
|
|
|
The joined room ID must be returned in the ``room_id`` field.
|
|
examples:
|
|
application/json: {
|
|
"room_id": "!d41d8cd:matrix.org"}
|
|
schema:
|
|
type: object
|
|
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.
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_FORBIDDEN", "error": "You are not invited to this room."}
|
|
429:
|
|
description: This request was rate-limited.
|
|
schema:
|
|
"$ref": "definitions/error.yaml"
|
|
tags:
|
|
- Room membership
|