async-matrix 0.1.3 → 1.0.0

data/data/matrix-spec/api/client-server/joining.yaml

@@ -0,0 +1,238 @@
+# 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: Join the requesting user to 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's participation 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: Join the requesting user to a particular room.
+      description: |-
+        *Note that this API takes either a room ID or alias, unlike* `/rooms/{roomId}/join`.
+
+        This API starts a user's participation 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: 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