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

README.rst

@@ -172,7 +172,7 @@ Examples:
 `improvement <https://github.com/matrix-org/matrix-doc/labels/improvement>`_
 ----------------------------------------------------------------------------
 
-A suggestion for a relaatively simple improvement to the protocol.
+A suggestion for a relatively simple improvement to the protocol.
 
 Examples:
 

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

changelogs/client_server.rst

@@ -1,7 +1,25 @@
 Unreleased changes
 ==================
 
-No changes as yet.
+- Changes to the API which will be backwards-compatible for clients:
+
+  - New endpoints:
+
+    - ``POST /user_directory/search``
+      (`#1096 <https://github.com/matrix-org/matrix-doc/pull/1096>`_).
+
+- Spec clarifications:
+
+  - Mark ``home_server`` return field for ``/login`` and ``/register``
+    endpoints as deprecated
+    (`#1097 <https://github.com/matrix-org/matrix-doc/pull/1097>`_).
+  - Fix response format of ``/keys/changes`` endpoint
+    (`#1106 <https://github.com/matrix-org/matrix-doc/pull/1106>`_)
+
+- Changes to the API which will be backwards-compatible for clients:
+
+  - Add 'token' parameter to /keys/query endpoint
+    (`#1104 <https://github.com/matrix-org/matrix-doc/pull/1104>`_).
 
 r0.3.0
 ======
@@ -61,6 +79,8 @@ r0.3.0
   - Add ``m.room.pinned_events`` state event for rooms.
     (`#1007 <https://github.com/matrix-org/matrix-doc/pull/1007>`_).
   - Add mention of ability to send Access Token via an Authorization Header.
+  - Add ``guest_can_join`` parameter to ``POST /createRoom``
+    (`#1093 <https://github.com/matrix-org/matrix-doc/pull/1093>`_).
 
   - New endpoints:
 

specification/appendices/identifier_grammar.rst

@@ -139,7 +139,7 @@ history includes events with a ``sender`` which does not conform. In order to
 handle these rooms successfully, clients and servers MUST accept user IDs with
 localparts from the expanded character set::
 
-  extended_user_id_char = %x21-7E
+  extended_user_id_char = %x21-39 / %x3B-7F  ; all ascii printing chars except :
 
 Mapping from other character sets
 <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

specification/client_server_api.rst

@@ -192,7 +192,7 @@ requests can be handled correctly.
 
 By default, the `Login`_ and `Registration`_ processes auto-generate a new
 ``device_id``. A client is also free to generate its own ``device_id`` or,
-provided the user remains the same, reuse a device: in ether case the client
+provided the user remains the same, reuse a device: in either case the client
 should pass the ``device_id`` in the request body. If the client sets the
 ``device_id``, the server will invalidate any access token previously assigned
 to that device. There is therefore at most one active access token assigned to
@@ -1335,13 +1335,23 @@ Listing rooms
 
 {{list_public_rooms_cs_http_api}}
 
+
+User Data
+---------
+
+User Directory
+~~~~~~~~~~~~~~
+
+{{users_cs_http_api}}
+
+
 Profiles
---------
+~~~~~~~~
 
 {{profile_cs_http_api}}
 
 Events on Change of Profile Information
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
++++++++++++++++++++++++++++++++++++++++
 Because the profile display name and avatar information are likely to be used in
 many places of a client's display, changes to these fields cause an automatic
 propagation event to occur, informing likely-interested parties of the new

specification/server_server_api.rst

@@ -941,11 +941,11 @@ following keys:
 ============== ===== ============
  Key            Type  Description
 ============== ===== ============
-``auth_chain`` List  A list of events giving the authorization chain for this
+``auth_chain`` List  A list of events giving all of the events in the auth
-                     join event
+                     chains for the join event and the events in ``state``.
 ``state``      List  A complete list of the prevailing state events at the
                      instant just before accepting the new ``m.room.member``
-                     event
+                     event.
 ============== ===== ============
 
 .. TODO-spec