diff --git a/README.rst b/README.rst index 5ceeae5f4..5c9edac78 100644 --- a/README.rst +++ b/README.rst @@ -172,7 +172,7 @@ Examples: `improvement `_ ---------------------------------------------------------------------------- -A suggestion for a relaatively simple improvement to the protocol. +A suggestion for a relatively simple improvement to the protocol. Examples: diff --git a/api/client-server/create_room.yaml b/api/client-server/create_room.yaml index 24382660d..bf632c1a1 100644 --- a/api/client-server/create_room.yaml +++ b/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. diff --git a/api/client-server/keys.yaml b/api/client-server/keys.yaml index 096e63b3c..5fb6318e9 100644 --- a/api/client-server/keys.yaml +++ b/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 diff --git a/api/client-server/login.yaml b/api/client-server/login.yaml index ff3eb392e..03a1622c0 100644 --- a/api/client-server/login.yaml +++ b/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: |- diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 52693f5b5..fd8f68328 100644 --- a/api/client-server/registration.yaml +++ b/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: |- diff --git a/api/client-server/users.yaml b/api/client-server/users.yaml new file mode 100644 index 000000000..1734e3bb8 --- /dev/null +++ b/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 diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index 4a26c302b..1e930e771 100644 --- a/changelogs/client_server.rst +++ b/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 `_). + +- Spec clarifications: + + - Mark ``home_server`` return field for ``/login`` and ``/register`` + endpoints as deprecated + (`#1097 `_). + - Fix response format of ``/keys/changes`` endpoint + (`#1106 `_) + +- Changes to the API which will be backwards-compatible for clients: + + - Add 'token' parameter to /keys/query endpoint + (`#1104 `_). r0.3.0 ====== @@ -61,6 +79,8 @@ r0.3.0 - Add ``m.room.pinned_events`` state event for rooms. (`#1007 `_). - Add mention of ability to send Access Token via an Authorization Header. + - Add ``guest_can_join`` parameter to ``POST /createRoom`` + (`#1093 `_). - New endpoints: diff --git a/specification/appendices/identifier_grammar.rst b/specification/appendices/identifier_grammar.rst index d53f61ac9..e85bf4107 100644 --- a/specification/appendices/identifier_grammar.rst +++ b/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 <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index e68aea438..464d20ae6 100644 --- a/specification/client_server_api.rst +++ b/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 diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 0770e38e8..43874321c 100644 --- a/specification/server_server_api.rst +++ b/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 - join event +``auth_chain`` List A list of events giving all of the events in the auth + 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