Update client-server API endpoints to move from r0 to v3 (plus whitespace fixes) (#3421)
* Blind find & replace all on client major version -> v3 * Fix up bad replacements * Fix anchors for r0->v3 * Changelog
This commit is contained in:
parent
2d98cd3084
commit
95d850c418
69 changed files with 206 additions and 210 deletions
|
@ -799,7 +799,7 @@ type, it can direct the user to a web browser with the URL of a fallback
|
|||
page which will allow the user to complete that login step out-of-band
|
||||
in their web browser. The URL it should open is:
|
||||
|
||||
/_matrix/client/%CLIENT_MAJOR_VERSION%/auth/<auth type>/fallback/web?session=<session ID>
|
||||
/_matrix/client/v3/auth/<auth type>/fallback/web?session=<session ID>
|
||||
|
||||
Where `auth type` is the type name of the stage it is attempting and
|
||||
`session ID` is the ID of the session given by the homeserver.
|
||||
|
@ -843,7 +843,7 @@ window which will handle unknown login types:
|
|||
* homeserverUrl: the base url of the homeserver (e.g. "https://matrix.org")
|
||||
*
|
||||
* apiEndpoint: the API endpoint being used (e.g.
|
||||
* "/_matrix/client/%CLIENT_MAJOR_VERSION%/account/password")
|
||||
* "/_matrix/client/v3/account/password")
|
||||
*
|
||||
* loginType: the loginType being attempted (e.g. "m.login.recaptcha")
|
||||
*
|
||||
|
@ -879,7 +879,7 @@ function unknownLoginType(homeserverUrl, apiEndpoint, loginType, sessionID, onCo
|
|||
window.addEventListener("message", eventListener);
|
||||
|
||||
var url = homeserverUrl +
|
||||
"/_matrix/client/%CLIENT_MAJOR_VERSION%/auth/" +
|
||||
"/_matrix/client/v3/auth/" +
|
||||
encodeURIComponent(loginType) +
|
||||
"/fallback/web?session=" +
|
||||
encodeURIComponent(sessionID);
|
||||
|
@ -1142,7 +1142,7 @@ Some examples of what should **not** be a capability are:
|
|||
- Whether the server supports a feature in the `unstable`
|
||||
specification.
|
||||
- Media size limits - these are handled by the
|
||||
`/media/%CLIENT_MAJOR_VERSION%/config` API.
|
||||
[`/config`](#get_matrixmediav3config) API.
|
||||
- Optional encodings or alternative transports for communicating with
|
||||
the server.
|
||||
|
||||
|
@ -1271,9 +1271,9 @@ The expected pattern for using lazy-loading is currently:
|
|||
|
||||
The current endpoints which support lazy-loading room members are:
|
||||
|
||||
- [`/sync`](/client-server-api/#get_matrixclientr0sync)
|
||||
- [`/rooms/<room_id>/messages`](/client-server-api/#get_matrixclientr0roomsroomidmessages)
|
||||
- [`/rooms/{roomId}/context/{eventId}`](/client-server-api/#get_matrixclientr0roomsroomidcontexteventid)
|
||||
- [`/sync`](/client-server-api/#get_matrixclientv3sync)
|
||||
- [`/rooms/<room_id>/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages)
|
||||
- [`/rooms/{roomId}/context/{eventId}`](/client-server-api/#get_matrixclientv3roomsroomidcontexteventid)
|
||||
|
||||
### API endpoints
|
||||
|
||||
|
@ -1419,13 +1419,13 @@ events.
|
|||
### Syncing
|
||||
|
||||
To read events, the intended flow of operation is for clients to first
|
||||
call the [`/sync`](/client-server-api/#get_matrixclientr0sync) API without a `since` parameter. This returns the
|
||||
call the [`/sync`](/client-server-api/#get_matrixclientv3sync) API without a `since` parameter. This returns the
|
||||
most recent message events for each room, as well as the state of the
|
||||
room at the start of the returned timeline. The response also includes a
|
||||
`next_batch` field, which should be used as the value of the `since`
|
||||
parameter in the next call to `/sync`. Finally, the response includes,
|
||||
for each room, a `prev_batch` field, which can be passed as a `start`
|
||||
parameter to the [`/rooms/<room_id>/messages`](/client-server-api/#get_matrixclientr0roomsroomidmessages) API to retrieve earlier
|
||||
parameter to the [`/rooms/<room_id>/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages) API to retrieve earlier
|
||||
messages.
|
||||
|
||||
You can visualise the range of events being returned as:
|
||||
|
@ -1462,7 +1462,7 @@ containing only the most recent message events. A state "delta" is also
|
|||
returned, summarising any state changes in the omitted part of the
|
||||
timeline. The client may therefore end up with "gaps" in its knowledge
|
||||
of the message timeline. The client can fill these gaps using the
|
||||
[`/rooms/<room_id>/messages`](/client-server-api/#get_matrixclientr0roomsroomidmessages) API. This situation looks like this:
|
||||
[`/rooms/<room_id>/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages) API. This situation looks like this:
|
||||
|
||||
```
|
||||
| gap |
|
||||
|
@ -1593,8 +1593,8 @@ some events cannot be simply deleted, e.g. membership events, we instead
|
|||
not required by the protocol. This stripped down event is thereafter
|
||||
returned anytime a client or remote server requests it. Redacting an
|
||||
event cannot be undone, allowing server owners to delete the offending
|
||||
content from the databases. Servers should include a copy of the
|
||||
`m.room.redaction` event under `unsigned` as `redacted_because`
|
||||
content from the databases. Servers should include a copy of the
|
||||
`m.room.redaction` event under `unsigned` as `redacted_because`
|
||||
when serving the redacted event to clients.
|
||||
|
||||
The exact algorithm to apply against an event is defined in the [room
|
||||
|
@ -1786,7 +1786,7 @@ must have been invited to or have joined the room before they are
|
|||
eligible to leave the room. Leaving a room to which the user has been
|
||||
invited rejects the invite, and can retract a knock. Once a user leaves
|
||||
a room, it will no longer appear in the response to the
|
||||
[`/sync`](/client-server-api/#get_matrixclientr0sync) API unless it is
|
||||
[`/sync`](/client-server-api/#get_matrixclientv3sync) API unless it is
|
||||
explicitly requested via a filter with the `include_leave` field set
|
||||
to `true`.
|
||||
|
||||
|
@ -1795,7 +1795,7 @@ Whether or not they actually joined the room, if the room is an
|
|||
re-join the room.
|
||||
|
||||
A user can also forget a room which they have left. Rooms which have
|
||||
been forgotten will never appear the response to the [`/sync`](/client-server-api/#get_matrixclientr0sync) API,
|
||||
been forgotten will never appear the response to the [`/sync`](/client-server-api/#get_matrixclientv3sync) API,
|
||||
until the user re-joins, is re-invited, or knocks.
|
||||
|
||||
A user may wish to force another user to leave a room. This can be done
|
||||
|
@ -1816,7 +1816,7 @@ target user to leave the room and prevents them from re-joining the
|
|||
room. A banned user will not be treated as a joined user, and so will
|
||||
not be able to send or receive events in the room. In order to ban
|
||||
someone, the user performing the ban MUST have the required power level.
|
||||
To ban a user, a request should be made to [`/rooms/<room_id>/ban`](/client-server-api/#post_matrixclientr0roomsroomidban)
|
||||
To ban a user, a request should be made to [`/rooms/<room_id>/ban`](/client-server-api/#post_matrixclientv3roomsroomidban)
|
||||
with:
|
||||
|
||||
```json
|
||||
|
@ -1838,7 +1838,7 @@ target member's state, by making a request to
|
|||
```
|
||||
|
||||
A user must be explicitly unbanned with a request to
|
||||
[`/rooms/<room_id>/unban`](/client-server-api/#post_matrixclientr0roomsroomidunban) before they can re-join the room or be
|
||||
[`/rooms/<room_id>/unban`](/client-server-api/#post_matrixclientv3roomsroomidunban) before they can re-join the room or be
|
||||
re-invited.
|
||||
|
||||
{{% http-api spec="client-server" api="banning" %}}
|
||||
|
|
|
@ -24,7 +24,7 @@ whether a chat is 'direct' to an invitee.
|
|||
#### Client behaviour
|
||||
|
||||
To start a direct chat with another user, the inviting user's client
|
||||
should set the `is_direct` flag to [`/createRoom`](/client-server-api/#post_matrixclientr0createroom). The client should do this
|
||||
should set the `is_direct` flag to [`/createRoom`](/client-server-api/#post_matrixclientv3createroom). The client should do this
|
||||
whenever the flow the user has followed is one where their intention is
|
||||
to speak directly with another person, as opposed to bringing that
|
||||
person in to a shared room. For example, clicking on 'Start Chat' beside
|
||||
|
@ -38,10 +38,10 @@ the flag altogether.
|
|||
|
||||
Both the inviting client and the invitee's client should record the fact
|
||||
that the room is a direct chat by storing an `m.direct` event in the
|
||||
account data using [`/user/<user_id>/account_data/<type>`](/client-server-api/#put_matrixclientr0useruseridaccount_datatype).
|
||||
account data using [`/user/<user_id>/account_data/<type>`](/client-server-api/#put_matrixclientv3useruseridaccount_datatype).
|
||||
|
||||
#### Server behaviour
|
||||
|
||||
When the `is_direct` flag is given to [`/createRoom`](/client-server-api/#post_matrixclientr0createroom), the home server must set the
|
||||
When the `is_direct` flag is given to [`/createRoom`](/client-server-api/#post_matrixclientv3createroom), the home server must set the
|
||||
`is_direct` flag in the invite member event for any users invited in the
|
||||
[`/createRoom`](/client-server-api/#post_matrixclientr0createroom) call.
|
||||
[`/createRoom`](/client-server-api/#post_matrixclientv3createroom) call.
|
||||
|
|
|
@ -113,13 +113,13 @@ key, and a number of signed Curve25519 one-time keys.
|
|||
##### Uploading keys
|
||||
|
||||
A device uploads the public parts of identity keys to their homeserver
|
||||
as a signed JSON object, using the [`/keys/upload`](/client-server-api/#post_matrixclientr0keysupload) API. The JSON object
|
||||
as a signed JSON object, using the [`/keys/upload`](/client-server-api/#post_matrixclientv3keysupload) API. The JSON object
|
||||
must include the public part of the device's Ed25519 key, and must be
|
||||
signed by that key, as described in [Signing
|
||||
JSON](/appendices/#signing-json).
|
||||
|
||||
One-time keys are also uploaded to the homeserver using the
|
||||
[`/keys/upload`](/client-server-api/#post_matrixclientr0keysupload) API.
|
||||
[`/keys/upload`](/client-server-api/#post_matrixclientv3keysupload) API.
|
||||
|
||||
Devices must store the private part of each key they upload. They can
|
||||
discard the private part of a one-time key when they receive a message
|
||||
|
@ -134,12 +134,12 @@ too many private keys may discard keys starting with the oldest.
|
|||
Before Alice can send an encrypted message to Bob, she needs a list of
|
||||
each of his devices and the associated identity keys, so that she can
|
||||
establish an encryption session with each device. This list can be
|
||||
obtained by calling [`/keys/query`](/client-server-api/#post_matrixclientr0keysquery), passing Bob's user ID in the
|
||||
obtained by calling [`/keys/query`](/client-server-api/#post_matrixclientv3keysquery), passing Bob's user ID in the
|
||||
`device_keys` parameter.
|
||||
|
||||
From time to time, Bob may add new devices, and Alice will need to know
|
||||
this so that she can include his new devices for later encrypted
|
||||
messages. A naive solution to this would be to call [`/keys/query`](/client-server-api/#post_matrixclientr0keysquery)
|
||||
messages. A naive solution to this would be to call [`/keys/query`](/client-server-api/#post_matrixclientv3keysquery)
|
||||
before sending each message -however, the number of users and devices
|
||||
may be large and this would be inefficient.
|
||||
|
||||
|
@ -157,23 +157,23 @@ process:
|
|||
list, and a separate flag to indicate that its list of Bob's devices
|
||||
is outdated. Both flags should be in storage which persists over
|
||||
client restarts.
|
||||
2. It then makes a request to [`/keys/query`](/client-server-api/#post_matrixclientr0keysquery), passing Bob's user ID in
|
||||
2. It then makes a request to [`/keys/query`](/client-server-api/#post_matrixclientv3keysquery), passing Bob's user ID in
|
||||
the `device_keys` parameter. When the request completes, it stores
|
||||
the resulting list of devices in persistent storage, and clears the
|
||||
'outdated' flag.
|
||||
3. During its normal processing of responses to [`/sync`](/client-server-api/#get_matrixclientr0sync), Alice's client
|
||||
3. During its normal processing of responses to [`/sync`](/client-server-api/#get_matrixclientv3sync), Alice's client
|
||||
inspects the `changed` property of the [`device_lists`](/client-server-api/#extensions-to-sync-1) field. If it
|
||||
is tracking the device lists of any of the listed users, then it
|
||||
marks the device lists for those users outdated, and initiates
|
||||
another request to [`/keys/query`](/client-server-api/#post_matrixclientr0keysquery) for them.
|
||||
another request to [`/keys/query`](/client-server-api/#post_matrixclientv3keysquery) for them.
|
||||
4. Periodically, Alice's client stores the `next_batch` field of the
|
||||
result from [`/sync`](/client-server-api/#get_matrixclientr0sync) in persistent storage. If Alice later restarts her
|
||||
result from [`/sync`](/client-server-api/#get_matrixclientv3sync) in persistent storage. If Alice later restarts her
|
||||
client, it can obtain a list of the users who have updated their
|
||||
device list while it was offline by calling [`/keys/changes`](/client-server-api/#get_matrixclientr0keyschanges),
|
||||
device list while it was offline by calling [`/keys/changes`](/client-server-api/#get_matrixclientv3keyschanges),
|
||||
passing the recorded `next_batch` field as the `from` parameter. If
|
||||
the client is tracking the device list of any of the users listed in
|
||||
the response, it marks them as outdated. It combines this list with
|
||||
those already flagged as outdated, and initiates a [`/keys/query`](/client-server-api/#post_matrixclientr0keysquery)
|
||||
those already flagged as outdated, and initiates a [`/keys/query`](/client-server-api/#post_matrixclientv3keysquery)
|
||||
request for all of them.
|
||||
|
||||
{{% boxes/warning %}}
|
||||
|
@ -339,7 +339,7 @@ Example:
|
|||
|
||||
A client wanting to set up a session with another device can claim a
|
||||
one-time key for that device. This is done by making a request to the
|
||||
[`/keys/claim`](/client-server-api/#post_matrixclientr0keysclaim) API.
|
||||
[`/keys/claim`](/client-server-api/#post_matrixclientv3keysclaim) API.
|
||||
|
||||
A homeserver should rate-limit the number of one-time keys that a given
|
||||
user or remote server can claim. A homeserver should discard the public
|
||||
|
@ -860,11 +860,11 @@ key, then Alice's device can trust Bob's master key, and she can sign it
|
|||
with her user-signing key.
|
||||
|
||||
Users upload their cross-signing keys to the server using [POST
|
||||
/\_matrix/client/r0/keys/device\_signing/upload](/client-server-api/#post_matrixclientr0keysdevice_signingupload). When Alice uploads
|
||||
/\_matrix/client/r0/keys/device\_signing/upload](/client-server-api/#post_matrixclientv3keysdevice_signingupload). When Alice uploads
|
||||
new cross-signing keys, her user ID will appear in the `changed`
|
||||
property of the `device_lists` field of the `/sync` of response of all
|
||||
users who share an encrypted room with her. When Bob sees Alice's user
|
||||
ID in his `/sync`, he will call [POST /\_matrix/client/r0/keys/query](/client-server-api/#post_matrixclientr0keysquery)
|
||||
ID in his `/sync`, he will call [POST /\_matrix/client/r0/keys/query](/client-server-api/#post_matrixclientv3keysquery)
|
||||
to retrieve Alice's device and cross-signing keys.
|
||||
|
||||
If Alice has a device and wishes to send an encrypted message to Bob,
|
||||
|
@ -1166,17 +1166,17 @@ However, as the session keys are stored on the server encrypted, it
|
|||
requires users to enter a decryption key to decrypt the session keys.
|
||||
|
||||
To create a backup, a client will call [POST
|
||||
/\_matrix/client/r0/room\_keys/version](#post_matrixclientr0room_keysversion) and define how the keys are to
|
||||
/\_matrix/client/r0/room\_keys/version](#post_matrixclientv3room_keysversion) and define how the keys are to
|
||||
be encrypted through the backup's `auth_data`; other clients can
|
||||
discover the backup by calling [GET
|
||||
/\_matrix/client/r0/room\_keys/version](#get_matrixclientr0room_keysversion). Keys are encrypted according
|
||||
/\_matrix/client/r0/room\_keys/version](#get_matrixclientv3room_keysversion). Keys are encrypted according
|
||||
to the backup's `auth_data` and added to the backup by calling [PUT
|
||||
/\_matrix/client/r0/room\_keys/keys](#put_matrixclientr0room_keyskeys) or one of its variants, and can
|
||||
be retrieved by calling [GET /\_matrix/client/r0/room\_keys/keys](#get_matrixclientr0room_keyskeys) or
|
||||
/\_matrix/client/r0/room\_keys/keys](#put_matrixclientv3room_keyskeys) or one of its variants, and can
|
||||
be retrieved by calling [GET /\_matrix/client/r0/room\_keys/keys](#get_matrixclientv3room_keyskeys) or
|
||||
one of its variants. Keys can only be written to the most recently
|
||||
created version of the backup. Backups can also be deleted using [DELETE
|
||||
/\_matrix/client/r0/room\_keys/version/{version}](#delete_matrixclientr0room_keysversionversion), or individual keys
|
||||
can be deleted using [DELETE /\_matrix/client/r0/room\_keys/keys](#delete_matrixclientr0room_keyskeys) or
|
||||
/\_matrix/client/r0/room\_keys/version/{version}](#delete_matrixclientv3room_keysversionversion), or individual keys
|
||||
can be deleted using [DELETE /\_matrix/client/r0/room\_keys/keys](#delete_matrixclientv3room_keyskeys) or
|
||||
one of its variants.
|
||||
|
||||
Clients must only store keys in backups after they have ensured that the
|
||||
|
@ -1458,7 +1458,7 @@ correspond to the user who sent the event, `recipient` to the local
|
|||
user, and `recipient_keys` to the local ed25519 key.
|
||||
|
||||
Clients must confirm that the `sender_key` and the `ed25519` field value
|
||||
under the `keys` property match the keys returned by [`/keys/query`](/client-server-api/#post_matrixclientr0keysquery) for
|
||||
under the `keys` property match the keys returned by [`/keys/query`](/client-server-api/#post_matrixclientv3keysquery) for
|
||||
the given user, and must also verify the signature of the payload.
|
||||
Without this check, a client cannot be sure that the sender device owns
|
||||
the private part of the ed25519 key it claims to have in the Olm
|
||||
|
@ -1590,17 +1590,17 @@ messages.
|
|||
|
||||
##### Extensions to /sync
|
||||
|
||||
This module adds an optional `device_lists` property to the [`/sync`](/client-server-api/#get_matrixclientr0sync) response,
|
||||
This module adds an optional `device_lists` property to the [`/sync`](/client-server-api/#get_matrixclientv3sync) response,
|
||||
as specified below. The server need only populate this property for an
|
||||
incremental `/sync` (i.e., one where the `since` parameter was
|
||||
specified). The client is expected to use [`/keys/query`](/client-server-api/#post_matrixclientr0keysquery) or
|
||||
[`/keys/changes`](/client-server-api/#get_matrixclientr0keyschanges) for the equivalent functionality after an initial
|
||||
specified). The client is expected to use [`/keys/query`](/client-server-api/#post_matrixclientv3keysquery) or
|
||||
[`/keys/changes`](/client-server-api/#get_matrixclientv3keyschanges) for the equivalent functionality after an initial
|
||||
sync, as documented in [Tracking the device list for a
|
||||
user](#tracking-the-device-list-for-a-user).
|
||||
|
||||
It also adds a `one_time_keys_count` property. Note the spelling
|
||||
difference with the `one_time_key_counts` property in the
|
||||
[`/keys/upload`](/client-server-api/#post_matrixclientr0keysupload) response.
|
||||
[`/keys/upload`](/client-server-api/#post_matrixclientv3keysupload) response.
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|----------------------------|--------------------|------------------------------------------------------------------------------------------------------------------------|
|
||||
|
|
|
@ -12,7 +12,7 @@ should interact with servers in order to participate in rooms as guests.
|
|||
|
||||
Guest users retrieve access tokens from a homeserver using the ordinary
|
||||
[register
|
||||
endpoint](#post_matrixclientr0register),
|
||||
endpoint](#post_matrixclientv3register),
|
||||
specifying the `kind` parameter as `guest`. They may then interact with
|
||||
the client-server API as any other user would, but will only have access
|
||||
to a subset of the API as described the Client behaviour subsection
|
||||
|
@ -39,38 +39,38 @@ rather than allowing all homeservers to enforce the rules on each other.
|
|||
The following API endpoints are allowed to be accessed by guest accounts
|
||||
for retrieving events:
|
||||
|
||||
- [GET /rooms/:room\_id/state](#get_matrixclientr0roomsroomidstate)
|
||||
- [GET /rooms/:room\_id/context/:event\_id](#get_matrixclientr0roomsroomidcontexteventid)
|
||||
- [GET /rooms/:room\_id/event/:event\_id](#get_matrixclientr0roomsroomideventeventid)
|
||||
- [GET /rooms/:room\_id/state/:event\_type/:state\_key](#get_matrixclientr0roomsroomidstateeventtypestatekey)
|
||||
- [GET /rooms/:room\_id/messages](#get_matrixclientr0roomsroomidmessages)
|
||||
- [GET /rooms/:room\_id/members](#get_matrixclientr0roomsroomidmembers)
|
||||
- [GET /rooms/:room\_id/initialSync](#get_matrixclientr0roomsroomidinitialsync)
|
||||
- [GET /sync](#get_matrixclientr0sync)
|
||||
- [GET /events](#get_matrixclientr0events) as used for room previews.
|
||||
- [GET /rooms/:room\_id/state](#get_matrixclientv3roomsroomidstate)
|
||||
- [GET /rooms/:room\_id/context/:event\_id](#get_matrixclientv3roomsroomidcontexteventid)
|
||||
- [GET /rooms/:room\_id/event/:event\_id](#get_matrixclientv3roomsroomideventeventid)
|
||||
- [GET /rooms/:room\_id/state/:event\_type/:state\_key](#get_matrixclientv3roomsroomidstateeventtypestatekey)
|
||||
- [GET /rooms/:room\_id/messages](#get_matrixclientv3roomsroomidmessages)
|
||||
- [GET /rooms/:room\_id/members](#get_matrixclientv3roomsroomidmembers)
|
||||
- [GET /rooms/:room\_id/initialSync](#get_matrixclientv3roomsroomidinitialsync)
|
||||
- [GET /sync](#get_matrixclientv3sync)
|
||||
- [GET /events](#get_matrixclientv3events) as used for room previews.
|
||||
|
||||
The following API endpoints are allowed to be accessed by guest accounts
|
||||
for sending events:
|
||||
|
||||
- [POST /rooms/:room\_id/join](#post_matrixclientr0roomsroomidjoin)
|
||||
- [POST /rooms/:room\_id/leave](#post_matrixclientr0roomsroomidleave)
|
||||
- [PUT /rooms/:room\_id/send/m.room.message/:txn\_id](#put_matrixclientr0roomsroomidsendeventtypetxnid)
|
||||
- [PUT /sendToDevice/{eventType}/{txnId}](#put_matrixclientr0sendtodeviceeventtypetxnid)
|
||||
- [POST /rooms/:room\_id/join](#post_matrixclientv3roomsroomidjoin)
|
||||
- [POST /rooms/:room\_id/leave](#post_matrixclientv3roomsroomidleave)
|
||||
- [PUT /rooms/:room\_id/send/m.room.message/:txn\_id](#put_matrixclientv3roomsroomidsendeventtypetxnid)
|
||||
- [PUT /sendToDevice/{eventType}/{txnId}](#put_matrixclientv3sendtodeviceeventtypetxnid)
|
||||
|
||||
The following API endpoints are allowed to be accessed by guest accounts
|
||||
for their own account maintenance:
|
||||
|
||||
- [PUT /profile/:user\_id/displayname](#put_matrixclientr0profileuseriddisplayname)
|
||||
- [GET /devices](#get_matrixclientr0devices)
|
||||
- [GET /devices/{deviceId}](#get_matrixclientr0devicesdeviceid)
|
||||
- [PUT /devices/{deviceId}](#put_matrixclientr0devicesdeviceid)
|
||||
- [PUT /profile/:user\_id/displayname](#put_matrixclientv3profileuseriddisplayname)
|
||||
- [GET /devices](#get_matrixclientv3devices)
|
||||
- [GET /devices/{deviceId}](#get_matrixclientv3devicesdeviceid)
|
||||
- [PUT /devices/{deviceId}](#put_matrixclientv3devicesdeviceid)
|
||||
|
||||
The following API endpoints are allowed to be accessed by guest accounts
|
||||
for end-to-end encryption:
|
||||
|
||||
- [POST /keys/upload](#post_matrixclientr0keysupload)
|
||||
- [POST /keys/query](#post_matrixclientr0keysquery)
|
||||
- [POST /keys/claim](#post_matrixclientr0keysclaim)
|
||||
- [POST /keys/upload](#post_matrixclientv3keysupload)
|
||||
- [POST /keys/query](#post_matrixclientv3keysquery)
|
||||
- [POST /keys/claim](#post_matrixclientv3keysclaim)
|
||||
|
||||
#### Server behaviour
|
||||
|
||||
|
|
|
@ -17,7 +17,7 @@ and servers can implement the ignoring of users.
|
|||
|
||||
To ignore a user, effectively blocking them, the client should add the
|
||||
target user to the `m.ignored_user_list` event in their account data
|
||||
using [`/user/<user_id>/account_data/<type>`](/client-server-api/#put_matrixclientr0useruseridaccount_datatype). Once ignored, the client will no longer receive events sent by
|
||||
using [`/user/<user_id>/account_data/<type>`](/client-server-api/#put_matrixclientv3useruseridaccount_datatype). Once ignored, the client will no longer receive events sent by
|
||||
that user, with the exception of state events. The client should either
|
||||
hide previous content sent by the newly ignored user or perform a new
|
||||
`/sync` with no previous token.
|
||||
|
|
|
@ -54,31 +54,31 @@ such as Apple's APNS or Google's GCM. This happens as follows:
|
|||
|
||||
Definitions for terms used in this section are below:
|
||||
|
||||
Push Provider
|
||||
Push Provider
|
||||
A push provider is a service managed by the device vendor which can send
|
||||
notifications directly to the device. Google Cloud Messaging (GCM) and
|
||||
Apple Push Notification Service (APNS) are two examples of push
|
||||
providers.
|
||||
|
||||
Push Gateway
|
||||
Push Gateway
|
||||
A push gateway is a server that receives HTTP event notifications from
|
||||
homeservers and passes them on to a different protocol such as APNS for
|
||||
iOS devices or GCM for Android devices. Clients inform the homeserver
|
||||
which Push Gateway to send notifications to when it sets up a Pusher.
|
||||
|
||||
Pusher
|
||||
Pusher
|
||||
A pusher is a worker on the homeserver that manages the sending of HTTP
|
||||
notifications for a user. A user can have multiple pushers: one per
|
||||
device.
|
||||
|
||||
Push Rule
|
||||
Push Rule
|
||||
A push rule is a single rule that states under what *conditions* an
|
||||
event should be passed onto a push gateway and *how* the notification
|
||||
should be presented. These rules are stored on the user's homeserver.
|
||||
They are manually configured by the user, who can create and view them
|
||||
via the Client/Server API.
|
||||
|
||||
Push Ruleset
|
||||
Push Ruleset
|
||||
A push ruleset *scopes a set of rules according to some criteria*. For
|
||||
example, some rules may only be applied for messages from a particular
|
||||
sender, a particular room, or by default. The push ruleset contains the
|
||||
|
@ -123,25 +123,25 @@ the value of `kind`.
|
|||
|
||||
The different `kind`s of rule, in the order that they are checked, are:
|
||||
|
||||
Override Rules `override`
|
||||
Override Rules `override`
|
||||
The highest priority rules are user-configured overrides.
|
||||
|
||||
Content-specific Rules `content`
|
||||
Content-specific Rules `content`
|
||||
These configure behaviour for (unencrypted) messages that match certain
|
||||
patterns. Content rules take one parameter: `pattern`, that gives the
|
||||
glob pattern to match against. This is treated in the same way as
|
||||
`pattern` for `event_match`.
|
||||
|
||||
Room-specific Rules `room`
|
||||
Room-specific Rules `room`
|
||||
These rules change the behaviour of all messages for a given room. The
|
||||
`rule_id` of a room rule is always the ID of the room that it affects.
|
||||
|
||||
Sender-specific rules `sender`
|
||||
Sender-specific rules `sender`
|
||||
These rules configure notification behaviour for messages from a
|
||||
specific Matrix user ID. The `rule_id` of Sender rules is always the
|
||||
Matrix user ID of the user whose messages they'd apply to.
|
||||
|
||||
Underride rules `underride`
|
||||
Underride rules `underride`
|
||||
These are identical to `override` rules, but have a lower priority than
|
||||
`content`, `room` and `sender` rules.
|
||||
|
||||
|
@ -164,19 +164,19 @@ All rules have an associated list of `actions`. An action affects if and
|
|||
how a notification is delivered for a matching event. The following
|
||||
actions are defined:
|
||||
|
||||
`notify`
|
||||
`notify`
|
||||
This causes each matching event to generate a notification.
|
||||
|
||||
`dont_notify`
|
||||
`dont_notify`
|
||||
This prevents each matching event from generating a notification
|
||||
|
||||
`coalesce`
|
||||
`coalesce`
|
||||
This enables notifications for matching events but activates homeserver
|
||||
specific behaviour to intelligently coalesce multiple events into a
|
||||
single notification. Not all homeservers may support this. Those that do
|
||||
not support it should treat it as the `notify` action.
|
||||
|
||||
`set_tweak`
|
||||
`set_tweak`
|
||||
Sets an entry in the `tweaks` dictionary key that is sent in the
|
||||
notification request to the Push Gateway. This takes the form of a
|
||||
dictionary with a `set_tweak` key whose value is the name of the tweak
|
||||
|
@ -215,7 +215,7 @@ conditions must hold true for an event in order for the rule to match. A
|
|||
rule with no conditions always matches. The following conditions are
|
||||
defined:
|
||||
|
||||
`event_match`
|
||||
`event_match`
|
||||
This is a glob pattern match on a field of the event. Parameters:
|
||||
|
||||
- `key`: The dot-separated field of the event to match, e.g.
|
||||
|
@ -224,13 +224,13 @@ This is a glob pattern match on a field of the event. Parameters:
|
|||
special glob characters should be treated as having asterisks
|
||||
prepended and appended when testing the condition.
|
||||
|
||||
`contains_display_name`
|
||||
`contains_display_name`
|
||||
This matches unencrypted messages where `content.body` contains the
|
||||
owner's display name in that room. This is a separate rule because
|
||||
display names may change and as such it would be hard to maintain a rule
|
||||
that matched the user's display name. This condition has no parameters.
|
||||
|
||||
`room_member_count`
|
||||
`room_member_count`
|
||||
This matches the current number of members in the room. Parameters:
|
||||
|
||||
- `is`: A decimal integer optionally prefixed by one of, `==`, `<`,
|
||||
|
@ -238,7 +238,7 @@ This matches the current number of members in the room. Parameters:
|
|||
count is strictly less than the given number and so forth. If no
|
||||
prefix is present, this parameter defaults to `==`.
|
||||
|
||||
`sender_notification_permission`
|
||||
`sender_notification_permission`
|
||||
This takes into account the current power levels in the room, ensuring
|
||||
the sender of the event has high enough power to trigger the
|
||||
notification.
|
||||
|
@ -667,14 +667,14 @@ The content of the event is the current push rules for the user.
|
|||
To create a rule that suppresses notifications for the room with ID
|
||||
`!dj234r78wl45Gh4D:matrix.org`:
|
||||
|
||||
curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/%CLIENT_MAJOR_VERSION%/pushrules/global/room/%21dj234r78wl45Gh4D%3Amatrix.org?access_token=123456" -d \
|
||||
curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/v3/pushrules/global/room/%21dj234r78wl45Gh4D%3Amatrix.org?access_token=123456" -d \
|
||||
'{
|
||||
"actions" : ["dont_notify"]
|
||||
}'
|
||||
|
||||
To suppress notifications for the user `@spambot:matrix.org`:
|
||||
|
||||
curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/%CLIENT_MAJOR_VERSION%/pushrules/global/sender/%40spambot%3Amatrix.org?access_token=123456" -d \
|
||||
curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/v3/pushrules/global/sender/%40spambot%3Amatrix.org?access_token=123456" -d \
|
||||
'{
|
||||
"actions" : ["dont_notify"]
|
||||
}'
|
||||
|
@ -682,7 +682,7 @@ To suppress notifications for the user `@spambot:matrix.org`:
|
|||
To always notify for messages that contain the work 'cake' and set a
|
||||
specific sound (with a rule\_id of `SSByZWFsbHkgbGlrZSBjYWtl`):
|
||||
|
||||
curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/%CLIENT_MAJOR_VERSION%/pushrules/global/content/SSByZWFsbHkgbGlrZSBjYWtl?access_token=123456" -d \
|
||||
curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/v3/pushrules/global/content/SSByZWFsbHkgbGlrZSBjYWtl?access_token=123456" -d \
|
||||
'{
|
||||
"pattern": "cake",
|
||||
"actions" : ["notify", {"set_sound":"cakealarm.wav"}]
|
||||
|
@ -691,7 +691,7 @@ specific sound (with a rule\_id of `SSByZWFsbHkgbGlrZSBjYWtl`):
|
|||
To add a rule suppressing notifications for messages starting with
|
||||
'cake' but ending with 'lie', superseding the previous rule:
|
||||
|
||||
curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/%CLIENT_MAJOR_VERSION%/pushrules/global/content/U3BvbmdlIGNha2UgaXMgYmVzdA?access_token=123456&before=SSByZWFsbHkgbGlrZSBjYWtl" -d \
|
||||
curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/v3/pushrules/global/content/U3BvbmdlIGNha2UgaXMgYmVzdA?access_token=123456&before=SSByZWFsbHkgbGlrZSBjYWtl" -d \
|
||||
'{
|
||||
"pattern": "cake*lie",
|
||||
"actions" : ["notify"]
|
||||
|
@ -701,7 +701,7 @@ To add a custom sound for notifications messages containing the word
|
|||
'beer' in any rooms with 10 members or fewer (with greater importance
|
||||
than the room, sender and content rules):
|
||||
|
||||
curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/%CLIENT_MAJOR_VERSION%/pushrules/global/override/U2VlIHlvdSBpbiBUaGUgRHVrZQ?access_token=123456" -d \
|
||||
curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/v3/pushrules/global/override/U2VlIHlvdSBpbiBUaGUgRHVrZQ?access_token=123456" -d \
|
||||
'{
|
||||
"conditions": [
|
||||
{"kind": "event_match", "key": "content.body", "pattern": "beer" },
|
||||
|
|
|
@ -11,18 +11,18 @@ This can be particularly effective when combined with [Guest Access](#guest-acce
|
|||
|
||||
Previews are implemented via the `world_readable` [Room History
|
||||
Visibility](#room-history-visibility). setting, along with a special version of the [GET
|
||||
/events](#get_matrixclientr0events) endpoint.
|
||||
/events](#get_matrixclientv3events) endpoint.
|
||||
|
||||
#### Client behaviour
|
||||
|
||||
A client wishing to view a room without joining it should call [GET
|
||||
/rooms/:room\_id/initialSync](#get_matrixclientr0roomsroomidinitialsync),
|
||||
followed by [GET /events](#get_matrixclientr0events). Clients will need to do
|
||||
/rooms/:room\_id/initialSync](#get_matrixclientv3roomsroomidinitialsync),
|
||||
followed by [GET /events](#get_matrixclientv3events). Clients will need to do
|
||||
this in parallel for each room they wish to view.
|
||||
|
||||
Clients can of course also call other endpoints such as [GET
|
||||
/rooms/:room\_id/messages](#get_matrixclientr0roomsroomidmessages)
|
||||
and [GET /search](#post_matrixclientr0search) to
|
||||
/rooms/:room\_id/messages](#get_matrixclientv3roomsroomidmessages)
|
||||
and [GET /search](#post_matrixclientv3search) to
|
||||
access events outside the `/events` stream.
|
||||
|
||||
{{% http-api spec="client-server" api="peeking_events" %}}
|
||||
|
|
|
@ -13,19 +13,19 @@ client device.
|
|||
The primary motivation for this API is exchanging data that is
|
||||
meaningless or undesirable to persist in the room DAG - for example,
|
||||
one-time authentication tokens or key data. It is not intended for
|
||||
conversational data, which should be sent using the normal [`/rooms/<room_id>/send`](/client-server-api/#put_matrixclientr0roomsroomidsendeventtypetxnid) API for
|
||||
conversational data, which should be sent using the normal [`/rooms/<room_id>/send`](/client-server-api/#put_matrixclientv3roomsroomidsendeventtypetxnid) API for
|
||||
consistency throughout Matrix.
|
||||
|
||||
#### Client behaviour
|
||||
|
||||
To send a message to other devices, a client should call
|
||||
[`/sendToDevice`](/client-server-api/#put_matrixclientr0sendtodeviceeventtypetxnid). Only one message can be sent to each device per
|
||||
[`/sendToDevice`](/client-server-api/#put_matrixclientv3sendtodeviceeventtypetxnid). Only one message can be sent to each device per
|
||||
transaction, and they must all have the same event type. The device ID
|
||||
in the request body can be set to `*` to request that the message be
|
||||
sent to all known devices.
|
||||
|
||||
If there are send-to-device messages waiting for a client, they will be
|
||||
returned by [`/sync`](/client-server-api/#get_matrixclientr0sync), as detailed in [Extensions to /sync](/client-server-api/#extensions-to-sync). Clients should
|
||||
returned by [`/sync`](/client-server-api/#get_matrixclientv3sync), as detailed in [Extensions to /sync](/client-server-api/#extensions-to-sync). Clients should
|
||||
inspect the `type` of each returned event, and ignore any they do not
|
||||
understand.
|
||||
|
||||
|
@ -33,7 +33,7 @@ understand.
|
|||
|
||||
Servers should store pending messages for local users until they are
|
||||
successfully delivered to the destination device. When a client calls
|
||||
[`/sync`](/client-server-api/#get_matrixclientr0sync)
|
||||
[`/sync`](/client-server-api/#get_matrixclientv3sync)
|
||||
with an access token which corresponds to a device with pending
|
||||
messages, the server should list the pending messages, in order of
|
||||
arrival, in the response body.
|
||||
|
@ -57,7 +57,7 @@ should be sent on to the remote servers via
|
|||
|
||||
##### Extensions to /sync
|
||||
|
||||
This module adds the following properties to the [`/sync`](/client-server-api/#get_matrixclientr0sync) response:
|
||||
This module adds the following properties to the [`/sync`](/client-server-api/#get_matrixclientv3sync) response:
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|-----------|-----------------------------------------------------------------------------|
|
||||
|
|
|
@ -47,12 +47,12 @@ buttons. These are known as "identity providers" (IdPs).
|
|||
|
||||
An overview of the process is as follows:
|
||||
|
||||
1. The Matrix client calls [`GET /login`](/client-server-api/#get_matrixclientr0login) to find the supported login
|
||||
1. The Matrix client calls [`GET /login`](/client-server-api/#get_matrixclientv3login) to find the supported login
|
||||
types, and the homeserver includes a flow with
|
||||
`"type": "m.login.sso"` in the response.
|
||||
2. To initiate the `m.login.sso` login type, the Matrix client
|
||||
instructs the user's browser to navigate to the
|
||||
[`/login/sso/redirect`](/client-server-api/#get_matrixclientr0loginssoredirect) endpoint on the user's homeserver.
|
||||
[`/login/sso/redirect`](/client-server-api/#get_matrixclientv3loginssoredirect) endpoint on the user's homeserver.
|
||||
Note that this may be the IdP-dependent version of the endpoint if the
|
||||
user has selected one of the `identity_providers` from the flow.
|
||||
3. The homeserver responds with an HTTP redirect to the SSO user
|
||||
|
@ -63,7 +63,7 @@ An overview of the process is as follows:
|
|||
5. The browser is directed to the `redirectUrl` provided by the client
|
||||
with a `loginToken` query parameter for the client to log in with.
|
||||
6. The client exchanges the login token for an access token by calling
|
||||
the [`/login`](/client-server-api/#post_matrixclientr0login) endpoint with a `type` of `m.login.token`.
|
||||
the [`/login`](/client-server-api/#post_matrixclientv3login) endpoint with a `type` of `m.login.token`.
|
||||
|
||||
For native applications, typically steps 1 to 4 are carried out by
|
||||
opening an embedded web view.
|
||||
|
@ -108,8 +108,8 @@ otherwise the same.
|
|||
##### Client behaviour
|
||||
|
||||
The client starts the process by instructing the browser to navigate to
|
||||
[`/login/sso/redirect`](/client-server-api/#get_matrixclientr0loginssoredirect)
|
||||
(or [`/login/sso/redirect/{idpId}`](/client-server-api/#get_matrixclientr0loginssoredirectidpid)
|
||||
[`/login/sso/redirect`](/client-server-api/#get_matrixclientv3loginssoredirect)
|
||||
(or [`/login/sso/redirect/{idpId}`](/client-server-api/#get_matrixclientv3loginssoredirectidpid)
|
||||
when using one of the `identity_providers`)
|
||||
with an appropriate `redirectUrl`. Once
|
||||
authentication is successful, the browser will be redirected to that
|
||||
|
@ -159,7 +159,7 @@ the generic `/redirect` endpoint instead of the `/redirect/{idpId}` endpoint.
|
|||
###### Redirecting to the Authentication server
|
||||
|
||||
The server should handle
|
||||
`/_matrix/client/%CLIENT_MAJOR_VERSION%/login/sso/redirect` as follows:
|
||||
`/_matrix/client/v3/login/sso/redirect` as follows:
|
||||
|
||||
1. It should build a suitable request for the SSO system.
|
||||
2. It should store enough state that the flow can be securely resumed
|
||||
|
@ -193,11 +193,11 @@ The homeserver then proceeds as follows:
|
|||
registered as a new user.
|
||||
3. The homeserver should generate a short-term login token. This is an
|
||||
opaque token, suitable for use with the `m.login.token` type of the
|
||||
[`/login`](/client-server-api/#post_matrixclientr0login) API. The lifetime of this token SHOULD be limited to
|
||||
[`/login`](/client-server-api/#post_matrixclientv3login) API. The lifetime of this token SHOULD be limited to
|
||||
around five seconds.
|
||||
4. The homeserver adds a query parameter of `loginToken`, with the
|
||||
value of the generated login token, to the `redirectUrl` given in
|
||||
the `/_matrix/client/%CLIENT_MAJOR_VERSION%/login/sso/redirect`
|
||||
the `/_matrix/client/v3/login/sso/redirect`
|
||||
request. (Note: `redirectURL` may or may not include existing query
|
||||
parameters. If it already includes one or more `loginToken`
|
||||
parameters, they should be removed before adding the new one.)
|
||||
|
@ -219,7 +219,7 @@ The homeserver then proceeds as follows:
|
|||
are happy to grant access to their matrix account to the site named
|
||||
in the `redirectUrl`. This can be done either *before* redirecting
|
||||
to the SSO login page when handling the
|
||||
`/_matrix/client/%CLIENT_MAJOR_VERSION%/login/sso/redirect`
|
||||
`/_matrix/client/v3/login/sso/redirect`
|
||||
endpoint, or *after* login when handling the callback from the
|
||||
authentication server. (If the check is performed before
|
||||
redirecting, it is particularly important that the homeserver guards
|
||||
|
@ -232,7 +232,7 @@ The homeserver then proceeds as follows:
|
|||
2. For added security, homeservers SHOULD guard against unsolicited
|
||||
authentication attempts by tracking pending requests. One way to do
|
||||
this is to set a cookie when handling
|
||||
`/_matrix/client/%CLIENT_MAJOR_VERSION%/login/sso/redirect`, which
|
||||
`/_matrix/client/v3/login/sso/redirect`, which
|
||||
is checked and cleared when handling the callback from the
|
||||
authentication server.
|
||||
|
||||
|
@ -254,7 +254,7 @@ Clients do not need to take any particular additional steps beyond
|
|||
ensuring that the fallback mechanism has been implemented, and treating
|
||||
the `m.login.sso` authentication type the same as any other unknown type
|
||||
(i.e. they should open a browser window for
|
||||
`/_matrix/client/%CLIENT_MAJOR_VERSION%/auth/m.login.sso/fallback/web?session=<session_id>`.
|
||||
`/_matrix/client/v3/auth/m.login.sso/fallback/web?session=<session_id>`.
|
||||
Once the flow has completed, the client retries the request with the
|
||||
session only.)
|
||||
|
||||
|
@ -263,9 +263,9 @@ session only.)
|
|||
##### Redirecting to the Authentication server
|
||||
|
||||
The server should handle
|
||||
`/_matrix/client/%CLIENT_MAJOR_VERSION%/auth/m.login.sso/fallback/web`
|
||||
`/_matrix/client/v3/auth/m.login.sso/fallback/web`
|
||||
in much the same way as
|
||||
`/_matrix/client/%CLIENT_MAJOR_VERSION%/login/sso/redirect`, which is to
|
||||
`/_matrix/client/v3/login/sso/redirect`, which is to
|
||||
say:
|
||||
|
||||
1. It should build a suitable request for the SSO system.
|
||||
|
@ -312,7 +312,7 @@ fallback completion](#fallback) page to the user's browser.
|
|||
|
||||
This confirmation could take place before redirecting to the SSO
|
||||
authentication page (when handling the
|
||||
`/_matrix/client/%CLIENT_MAJOR_VERSION%/auth/m.login.sso/fallback/web`
|
||||
`/_matrix/client/v3/auth/m.login.sso/fallback/web`
|
||||
endpoint), or *after* authentication when handling the callback from
|
||||
the authentication server. (If the check is performed before
|
||||
redirecting, it is particularly important that the homeserver guards
|
||||
|
@ -321,6 +321,6 @@ fallback completion](#fallback) page to the user's browser.
|
|||
2. For added security, homeservers SHOULD guard against unsolicited
|
||||
authentication attempts by tracking pending requests. One way to do
|
||||
this is to set a cookie when handling
|
||||
`/_matrix/client/%CLIENT_MAJOR_VERSION%/auth/m.login.sso/fallback/web`,
|
||||
`/_matrix/client/v3/auth/m.login.sso/fallback/web`,
|
||||
which is checked and cleared when handling the callback from the
|
||||
authentication server.
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue