Merge branch 'master' of https://github.com/matrix-org/matrix-doc into rooms/event

api/client-server/create_room.yaml

@@ -179,6 +179,10 @@ paths:
                   This flag makes the server set the ``is_direct`` flag on the
                   ``m.room.member`` events sent to the users in ``invite`` and
                   ``invite_3pid``. See `Direct Messaging`_ for more information.
+              guest_can_join:
+                type: boolean
+                description: |-
+                  Allows guests to join the room. See `Guest Access`_ for more information.
       responses:
         200:
           description: Information about the newly created room.

api/client-server/keys.yaml

@@ -1,4 +1,5 @@
 # Copyright 2016 OpenMarket Ltd
+# 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.
@@ -131,6 +132,13 @@ paths:
                     description: "device ID"
                 example:
                   "@alice:example.com": []
+              token:
+                type: string
+                description: |-
+                  If the client is fetching keys as a result of a device update received
+                  in a sync request, this should be the 'since' token of that sync request,
+                  or any later sync token. This allows the server to ensure its response
+                  contains the keys advertised by the notification in that sync.
             required:
               - device_keys
 
@@ -328,7 +336,7 @@ paths:
           schema:
             type: object
             properties:
-              changes:
+              changed:
                 type: array
                 items:
                   type: string
@@ -336,5 +344,14 @@ paths:
                   The Matrix User IDs of all users who updated their device
                   identity keys.
                 example: ["@alice:example.com", "@bob:example.org"]
+              left:
+                type: array
+                items:
+                  type: string
+                description: |-
+                  The Matrix User IDs of all users who may have left all
+                  the end-to-end encrypted rooms they previously shared
+                  with the user.
+                example: ["@clara:example.com", "@doug:example.org"]
       tags:
         - End-to-end encryption

api/client-server/login.yaml

@@ -96,7 +96,6 @@ paths:
             application/json: {
                 "user_id": "@cheeky_monkey:matrix.org",
                 "access_token": "abc123",
-                "home_server": "matrix.org",
                 "device_id": "GHTYAJCE"
               }
           schema:
@@ -112,7 +111,13 @@ paths:
                   This access token can then be used to authorize other requests.
               home_server:
                 type: string
-                description: The hostname of the homeserver on which the account has been registered.
+                description: |-
+                  The server_name of the homeserver on which the account has
+                  been registered.
+
+                  **Deprecated**. Clients should extract the server_name from
+                  ``user_id`` (by splitting at the first colon) if they require
+                  it. Note also that ``homeserver`` is not spelt this way.
               device_id:
                 type: string
                 description: |-

api/client-server/registration.yaml

@@ -124,7 +124,6 @@ paths:
             application/json: {
                 "user_id": "@cheeky_monkey:matrix.org",
                 "access_token": "abc123",
-                "home_server": "matrix.org",
                 "device_id": "GHTYAJCE"
               }
           schema:
@@ -144,7 +143,13 @@ paths:
                   This access token can then be used to authorize other requests.
               home_server:
                 type: string
-                description: The hostname of the homeserver on which the account has been registered.
+                description: |-
+                  The server_name of the homeserver on which the account has
+                  been registered.
+
+                  **Deprecated**. Clients should extract the server_name from
+                  ``user_id`` (by splitting at the first colon) if they require
+                  it. Note also that ``homeserver`` is not spelt this way.
               device_id:
                 type: string
                 description: |-

api/client-server/users.yaml

@@ -0,0 +1,100 @@
+# Copyright 2017 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 Client-Server User Directory 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:
+  "/user_directory/search":
+    post:
+      summary: Searches the user directory.
+      description: |-
+        This API performs a server-side search over all users registered on the server.
+        It searches user ID and displayname case-insensitively for users that you share a room with or that are in public rooms.
+      operationId: searchUserDirectory
+      security:
+        - accessToken: []
+      parameters:
+        - in: body
+          name: body
+          schema:
+            type: object
+            properties:
+              search_term:
+                type: string
+                description: The term to search for
+                example: "foo"
+              limit:
+                type: number
+                description: The maximum number of results to return (Defaults to 10).
+                example: 10
+            required: ["search_term"]
+      responses:
+        200:
+          description: The results of the search.
+          examples:
+            application/json: {
+                  "results": [
+                    {
+                      "user_id": "@foo:bar.com",
+                      "display_name": "Foo",
+                      "avatar_url": "mxc://bar.com/foo"
+                    }
+                  ],
+                  "limited": false
+              }
+          schema:
+            type: object
+            required: ["results", "limited"]
+            properties:
+              results:
+                type: array
+                description: Ordered by rank and then whether or not profile info is available.
+                items:
+                  title: User
+                  type: object
+                  required: ["user_id"]
+                  properties:
+                    user_id:
+                      type: string
+                      example: "@foo:bar.com"
+                      description: The user's matrix user ID.
+                    display_name:
+                      type: string
+                      example: "Foo"
+                      description: The display name of the user, if one exists.
+                    avatar_url:
+                      type: string
+                      example: "mxc://bar.com/foo"
+                      description: The avatar url, as an MXC, if one exists.
+              limited:
+                type: boolean
+                description: Indicates if the result list has been truncated by the limit.
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+      tags:
+        - User data