wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

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

Browse source
This commit is contained in:
Michael Telatynski 2018-01-30 21:27:02 +00:00
commit a9c3d94f24
No known key found for this signature in database
GPG key ID: 3F879DA5AD802A5E
10 changed files with 175 additions and 14 deletions
Download patch file Download diff file Expand all files Collapse all files

2
README.rst
View file

@ -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:

4
api/client-server/create_room.yaml
View file

@ -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.

19
api/client-server/keys.yaml
View file

@ -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

9
api/client-server/login.yaml
View file

@ -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: |-

9
api/client-server/registration.yaml
View file

@ -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: |-

100
api/client-server/users.yaml Normal file
View file

@ -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

22
changelogs/client_server.rst
View file

@ -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:

2
specification/appendices/identifier_grammar.rst
View file

@ -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
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

16
specification/client_server_api.rst
View file

@ -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

6
specification/server_server_api.rst
View file

@ -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