# 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 Join Room API" version: "1.0.0" host: localhost:8448 schemes: - https basePath: /_matrix/federation/v1 produces: - application/json paths: "/make_join/{roomId}/{userId}": get: summary: Get information required to make a join event for a room description: |- Asks the receiving server to return information that the sending server will need to prepare a join event to get into the room. This is part of the `Joining Rooms`_ handshake. operationId: makeJoin parameters: - in: path name: roomId type: string description: The room ID that is about to be joined required: true x-example: "!abc123:matrix.org" - in: path name: userId type: string description: The user ID the join event will be for required: true x-example: "@someone:example.org" responses: 200: description: |- An unsigned event that the server may now use as a template for the rest of the `Joining Rooms`_ handshake. schema: allOf: - $ref: "definitions/unsigned_pdu.yaml" - type: object properties: # Note: we override a bunch of parameters to change their descriptions sender: type: string description: The user ID of the joining member example: "@someone:example.org" origin: type: string description: The name of the resident homeserver example: "matrix.org" origin_server_ts: type: integer format: int64 description: A timestamp added by the resident 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 joining member example: "@someone:example.org" content: type: object title: Membership Event Content description: The content of the event example: {"membership": "join"} properties: membership: type: string description: The value ``join`` example: "join" required: ['membership'] depth: type: integer description: This field must be present but is ignored; it may be 0 example: 12 auth_events: type: array description: |- An event reference list containing the authorization events that would allow the member to join 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 examples: application/json: { "$ref": "examples/unsigned_pdu.json", "type": "m.room.member", "state_key": "@someone:example.org", "content": { "membership": "join" } } "/send_join/{roomId}/{eventId}": put: summary: Submit a signed join event to a resident server description: |- Submits a signed join event to the resident server for it to accept it into the room's graph. operationId: sendJoin parameters: - in: path name: roomId type: string description: The room ID that is about to be joined required: true x-example: "!abc123:matrix.org" - in: path name: eventId type: string description: The event ID for the join event required: true x-example: "$abc123:example.org" - in: body name: body type: object required: true schema: allOf: - $ref: "definitions/pdu.yaml" - type: object properties: # Note: we override a bunch of parameters to change their descriptions sender: type: string description: The user ID of the joining member example: "@someone:example.org" origin: type: string description: The name of the joining homeserver example: "matrix.org" origin_server_ts: type: integer format: int64 description: A timestamp added by the joining 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 joining member example: "@someone:example.org" content: type: object title: Membership Event Content description: The content of the event example: {"membership": "join"} properties: membership: type: string description: The value ``join`` example: "join" required: ['membership'] depth: type: integer description: This field must be present but is ignored; it may be 0 example: 12 auth_events: type: array description: |- An event reference list containing the authorization events that would allow the member to join 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 example: { "$ref": "examples/pdu.json", "type": "m.room.member", "state_key": "@someone:example.org", "content": { "membership": "join" } } responses: 200: description: |- The full state for the room, having accepted the join event schema: type: array minItems: 2 maxItems: 2 items: - type: integer description: The value ``200`` example: 200 - type: object title: Room State description: The state for the room properties: auth_chain: type: array description: The auth chain items: type: object properties: {} # TODO: Verify schema state: type: array description: The room state items: type: object properties: {} # TODO: Verify schema required: ["auth_chain", "state"] examples: application/json: [ 200, { # TODO: Use the appropriate refs (see TODOs in schema) "auth_chain": [], "state": [] } ]