Convert invites to swagger

The whole section reads like a description for the endpoint, and has been replaced by the swagger definition now (rather than at a later stage). All the same information should be kept.
pull/1413/head
Travis Ralston 6 years ago
parent f09c4fd286
commit 004998b98f

@ -0,0 +1,88 @@
# Copyright 2018 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.
type: object
title: Invite Event
description: An invite event
allOf:
- $ref: "pdu.yaml"
- type: object
properties:
# Note: we override a bunch of parameters to change their descriptions
sender:
type: string
# TODO: Verify/clarify this - it doesn't seem right, given this is a 'regular' invite
description: |-
The matrix ID of the user who sent the original ``m.room.third_party_invite``
example: "@someone:example.org"
origin:
type: string
description: The name of the inviting homeserver
example: "matrix.org"
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the inviting 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 invited member
example: "@joe:elsewhere.com"
content:
type: object
title: Membership Event Content
description: |-
The content of the event, matching what is available in the
`Client-Server API`_
example: {"membership": "invite"}
properties:
membership:
type: string
description: The value ``invite``
example: "invite"
required: ['membership']
auth_events:
type: array
description: |-
An event reference list containing the authorization events that would
allow the member to be invited to the room
items:
type: array
maxItems: 2
minItems: 2
items:
- type: string
title: Event ID
example: "$abc123:matrix.org"
- type: object
title: Event Hash
example: {
"sha256": "abase64encodedsha256hashshouldbe43byteslong"
}
properties:
sha256:
type: string
description: The event hash
example: abase64encodedsha256hashshouldbe43byteslong
required: ['sha256']
redacts:
type: string
description: Not used
required:
# Every other field is already flagged as required by the $ref
- state_key
- unsigned # TODO: apparently this is required?

@ -0,0 +1,84 @@
# Copyright 2018 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/v1
produces:
- application/json
paths:
"/invite/{roomId}/{eventId}":
put:
summary: Invites a user to a room
description: |-
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 users in the room.
operationId: sendInvite
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
required: true
x-example: "$abc123:example.org"
- in: body
name: body
type: object
required: true
schema:
$ref: "definitions/invite_event.yaml"
example: {
"$ref": "examples/pdu.json",
"type": "m.room.member",
"content": {
"membership": "invite"
}
}
responses:
200:
description: |-
The event with the invited server's signature added. All other fields of the events
should remain untouched.
schema:
type: array
minItems: 2
maxItems: 2
items:
- type: integer
description: The value ``200``
example: 200
- $ref: "definitions/invite_event.yaml"
examples:
application/json: [
200,
{
"$ref": "examples/pdu.json",
"type": "m.room.member",
"content": {
"membership": "invite"
}
}
]

@ -879,65 +879,7 @@ that requested by the requester in the ``v`` parameter).
Inviting to a room Inviting to a room
------------------ ------------------
When a user wishes to invite another user to a local room and the other user is {{invites_ss_http_api}}
on a different server, the inviting server will send a request to the invited
server::
PUT .../invite/{roomId}/{eventId}
The required fields in the JSON body are:
======================== ============ =========================================
Key Type Description
======================== ============ =========================================
``room_id`` String The room ID of the room. Must be the same
as the room ID specified in the path.
``event_id`` String The ID of the event. Must be the same as
the event ID specified in the path.
``type`` String The value ``m.room.member``.
``auth_events`` List An event-reference list containing the
IDs of the authorization events that
would allow this member to be invited in
the room.
``content`` Object The content of the event.
``depth`` Integer The depth of the event.
``origin`` String The name of the inviting homeserver.
``origin_server_ts`` Integer A timestamp added by the inviting
homeserver.
``prev_events`` List An event-reference list containing the
IDs of the immediate predecessor events.
``sender`` String The Matrix ID of the user who sent the
original ``m.room.third_party_invite``.
``state_key`` String The Matrix ID of the invited user.
``signatures`` Object The signature of the event from the
origin server.
``unsigned`` Object An object containing the properties that
aren't part of the signature's
computation.
======================== ============ =========================================
Where the ``content`` key contains the content for the ``m.room.member`` event
specified in the `Client-Server API`_. Note that the ``membership`` property of
the content must be ``invite``.
Upon receiving this request, the invited homeserver will append its signature to
the event and respond to the request with the following JSON body::
[
200,
"event": {...}
]
Where ``event`` contains the event signed by both homeservers, using the same
JSON keys as the initial request on ``/invite/{roomId}/{eventId}``. Note that,
except for the ``signatures`` object (which now contains an additional signature),
all of the event's keys remain the same as in the event initially provided.
This response format is due to a typo in Synapse, the first implementation of
Matrix's APIs, and is preserved to maintain compatibility.
Now that the event has been signed by both the inviting homeserver and the
invited homeserver, it can be sent to all of the users in the room.
Third-party invites Third-party invites
------------------- -------------------

Loading…
Cancel
Save