Add knocking to the spec

Spec for https://github.com/matrix-org/matrix-doc/pull/2998
Spec for https://github.com/matrix-org/matrix-doc/pull/2403

This deliberately does not help towards fixing https://github.com/matrix-org/matrix-doc/issues/3153 in order to remain consistent with prior room versions, and to keep the diff smaller on this change. A future change will address room version legibility.

data/api/client-server/knocking.yaml

@@ -0,0 +1,124 @@
+# Copyright 2021 The Matrix.org Foundation C.I.C.
+#
+# 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 Knocking 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:
+  "/knock/{roomIdOrAlias}":
+    post:
+      summary: Knock on a room, requesting permission to join.
+      description: |-
+        *Note that this API takes either a room ID or alias, unlike other membership APIs.*
+
+        This API "knocks" on the room to ask for permission to join, if the user
+        is allowed to knock on the room. Acceptance of the knock happens out of
+        band from this API, meaning that the client will have to watch for updates
+        regarding the acceptance/rejection of the knock.
+
+        If the room history settings allow, the user will still be able to see
+        history of the room while being in the "knock" state. The user will have
+        to accept the invitation to join the room (acceptance of knock) to see
+        messages reliably. See the `/join` endpoints for more information about
+        history visibility to the user.
+
+        The knock will appear as an entry in the response of the
+        [`/sync`](/client-server-api/#get_matrixclientr0sync) API.
+      operationId: knockRoom
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomIdOrAlias
+          description: The room identifier or alias to knock upon.
+          required: true
+          x-example: "#monkeys:matrix.org"
+        - in: query
+          type: array
+          items:
+            type: string
+          name: server_name
+          description: |-
+            The servers to attempt to knock on the room through. One of the servers
+            must be participating in the room.
+          x-example: ["matrix.org", "elsewhere.ca"]
+        - in: body
+          name: body
+          required: true
+          schema:
+            type: object
+            properties:
+              reason:
+                type: string
+                description: |-
+                  Optional reason to be included as the `reason` on the subsequent
+                  membership event.
+                example: "Looking for support"
+      responses:
+        200:
+          description: |-
+            The room has been knocked upon.
+
+            The knocked room ID must be returned in the `room_id` field.
+          examples:
+            application/json: {
+              "room_id": "!d41d8cd:matrix.org"
+            }
+          schema:
+            type: object
+            properties:
+              room_id:
+                type: string
+                description: The knocked room ID.
+            required: ["room_id"]
+        403:
+          description: |-
+            You do not have permission to knock on the room. A meaningful `errcode`
+            and description error text will be returned. Example reasons for rejection are:
+
+            - The room is not set up for knocking.
+            - The user has been banned from the room.
+          examples:
+            application/json: {
+              "errcode": "M_FORBIDDEN", "error": "You are not allowed to knock on this room."
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+        404:
+          description: |-
+            The room could not be found or resolved to a room ID.
+          examples:
+            application/json: {
+              "errcode": "M_NOT_FOUND", "error": "That room does not appear to exist."
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/errors/rate_limited.yaml"
+      tags:
+        - Room membership