-
Notifications
You must be signed in to change notification settings - Fork 384
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Original proposal: #1794 Implementation proofs: * matrix-org/synapse#4402 * matrix-org/synapse#4496 There are no changes from the original proposal.
- Loading branch information
Showing
3 changed files
with
246 additions
and
7 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,234 @@ | ||
| # Copyright 2018-2019 New Vector 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 Federation Invite User To Room API" | ||
| version: "1.0.0" | ||
| host: localhost:8448 | ||
| schemes: | ||
| - https | ||
| basePath: /_matrix/federation/v2 | ||
| consumes: | ||
| - application/json | ||
| produces: | ||
| - application/json | ||
| securityDefinitions: | ||
| $ref: definitions/security.yaml | ||
| paths: | ||
| "/invite/{roomId}/{eventId}": | ||
| put: | ||
| summary: Invites a remote user to a room | ||
| description: |- | ||
| .. Note:: | ||
| This API is nearly identical to the v1 API with the exception of the request | ||
| body being different, and the response format fixed. | ||
| Invites a remote user to a room. Once the event has been signed by both the inviting | ||
| homeserver and the invited homeserver, it can be sent to all of the servers in the | ||
| room by the inviting homeserver. | ||
| This endpoint is preferred over the v1 API as it is more useful for servers. Senders | ||
| which receive a 400 or 404 response to this endpoint may wish to retry using the v1 | ||
| API as the server may be older, if the room version supports doing so. | ||
| operationId: sendInviteV2 | ||
| security: | ||
| - signedRequest: [] | ||
| parameters: | ||
| - in: path | ||
| name: roomId | ||
| type: string | ||
| description: The room ID that the user is being invited to. | ||
| required: true | ||
| x-example: "!abc123:matrix.org" | ||
| - in: path | ||
| name: eventId | ||
| type: string | ||
| description: The event ID for the invite event, generated by the inviting server. | ||
| required: true | ||
| x-example: "$abc123:example.org" | ||
| - in: body | ||
| name: body | ||
| type: object | ||
| required: true | ||
| schema: | ||
| type: object | ||
| properties: | ||
| room_version: | ||
| type: string | ||
| description: The version of the room where the user is being invited to. | ||
| example: "2" | ||
| event: | ||
| $ref: "definitions/invite_event.yaml" | ||
| invite_room_state: | ||
| type: array | ||
| description: |- | ||
| An optional list of simplified events to help the receiver of the invite | ||
| identify the room. The recommended events to include are the join rules, | ||
| canonical alias, avatar, and name of the room. | ||
| items: | ||
| type: object | ||
| title: Invite Room State Event | ||
| properties: | ||
| type: | ||
| type: string | ||
| description: The type of event. | ||
| example: "m.room.join_rules" | ||
| state_key: | ||
| type: string | ||
| description: The state key for the event. May be an empty string. | ||
| example: "" | ||
| content: | ||
| type: object | ||
| description: The content for the event. | ||
| sender: | ||
| type: string | ||
| description: The sender of the event. | ||
| example: "@someone:matrix.org" | ||
| required: ['type', 'state_key', 'content', 'sender'] | ||
| example: [ | ||
| { | ||
| "type": "m.room.join_rules", | ||
| "sender": "@someone:matrix.org", | ||
| "state_key": "", | ||
| "content": { | ||
| "join_rule": "public" | ||
| } | ||
| } | ||
| ] | ||
| required: ['room_version', 'event'] | ||
| example: { | ||
| "room_version": "2", | ||
| "event": { | ||
| "$ref": "examples/pdu.json", | ||
| "type": "m.room.member", | ||
| "state_key": "@joe:elsewhere.com", | ||
| "content": { | ||
| "membership": "invite" | ||
| }, | ||
| "signatures": { | ||
| "example.com": { | ||
| "ed25519:key_version": "SomeSignatureHere" | ||
| }, | ||
| } | ||
| }, | ||
| "invite_room_state": [ | ||
| { | ||
| "type": "m.room.join_rules", | ||
| "sender": "@someone:matrix.org", | ||
| "state_key": "", | ||
| "content": { | ||
| "join_rule": "public" | ||
| } | ||
| }, | ||
| { | ||
| "type": "m.room.name", | ||
| "sender": "@someone:matrix.org", | ||
| "state_key": "", | ||
| "content": { | ||
| "name": "Cool New Room" | ||
| } | ||
| } | ||
| ] | ||
| } | ||
| responses: | ||
| 200: | ||
| description: |- | ||
| The event with the invited server's signature added. All other fields of the events | ||
| should remain untouched. | ||
| schema: | ||
| type: object | ||
| description: An object containing the signed invite event. | ||
| title: Event Container | ||
| properties: | ||
| event: | ||
| $ref: "definitions/invite_event.yaml" | ||
| required: ['event'] | ||
| examples: | ||
| application/json: { | ||
| "event": { | ||
| "$ref": "examples/pdu.json", | ||
| "type": "m.room.member", | ||
| "state_key": "@someone:example.org", | ||
| "unsigned": { | ||
| "invite_room_state": [ | ||
| { | ||
| "type": "m.room.join_rules", | ||
| "sender": "@someone:matrix.org", | ||
| "state_key": "", | ||
| "content": { | ||
| "join_rule": "public" | ||
| } | ||
| }, | ||
| { | ||
| "type": "m.room.name", | ||
| "sender": "@someone:matrix.org", | ||
| "state_key": "", | ||
| "content": { | ||
| "name": "Cool New Room" | ||
| } | ||
| } | ||
| ] | ||
| }, | ||
| "content": { | ||
| "membership": "invite" | ||
| }, | ||
| "signatures": { | ||
| "example.com": { | ||
| "ed25519:key_version": "SomeSignatureHere" | ||
| }, | ||
| "elsewhere.com": { | ||
| "ed25519:k3y_versi0n": "SomeOtherSignatureHere" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| 403: | ||
| description: |- | ||
| The invite is not allowed. This could be for a number of reasons, including: | ||
| * The sender is not allowed to send invites to the target user/homeserver. | ||
| * The homeserver does not permit anyone to invite its users. | ||
| * The homeserver refuses to participate in the room. | ||
| schema: | ||
| $ref: "../client-server/definitions/errors/error.yaml" | ||
| examples: | ||
| application/json: { | ||
| "errcode": "M_FORBIDDEN", | ||
| "error": "User cannot invite the target user." | ||
| } | ||
| 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" | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters