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

Add hyperlinks to endpoints (#2016)

Browse source 
... because there's nothing more infuriating than someone talking about an
endpoint, then having to search through 150 pages of spec for it.
This commit is contained in:
Richard van der Hoff 2024-12-09 11:03:53 +00:00 • committed by GitHub
parent 336b855d7a
commit 075a98d619
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
9 changed files with 40 additions and 36 deletions
Download patch file Download diff file Expand all files Collapse all files

1
changelogs/client_server/newsfragments/2016.clarification Normal file
View file

@ -0,0 +1 @@
Add hyperlinks throughout the specification.

51
content/client-server-api/_index.md
View file

@ -136,7 +136,7 @@ The request was not correctly authorized. Usually due to login failures.
`M_USER_DEACTIVATED` `M_USER_DEACTIVATED`
The user ID associated with the request has been deactivated. Typically The user ID associated with the request has been deactivated. Typically
for endpoints that prove authentication, such as `/login`. for endpoints that prove authentication, such as [`/login`](#get_matrixclientv3login).
`M_USER_IN_USE` `M_USER_IN_USE`
Encountered when trying to register a user ID which has been taken. Encountered when trying to register a user ID which has been taken.
@ -215,7 +215,8 @@ much memory or disk space. The error MUST have an `admin_contact` field
to provide the user receiving the error a place to reach out to. to provide the user receiving the error a place to reach out to.
Typically, this error will appear on routes which attempt to modify Typically, this error will appear on routes which attempt to modify
state (e.g.: sending messages, account data, etc) and not routes which state (e.g.: sending messages, account data, etc) and not routes which
only read state (e.g.: `/sync`, get account data, etc). only read state (e.g.: [`/sync`](#get_matrixclientv3sync),
[`/user/{userId}/account_data/{type}`](#get_matrixclientv3useruseridaccount_datatype), etc).
`M_CANNOT_LEAVE_SERVER_NOTICE_ROOM` `M_CANNOT_LEAVE_SERVER_NOTICE_ROOM`
The user is unable to reject an invite to join the server notices room. The user is unable to reject an invite to join the server notices room.
@ -266,7 +267,7 @@ HTTP request is the same.
Where a retransmission has been identified, the homeserver should return Where a retransmission has been identified, the homeserver should return
the same HTTP response code and content as the original request. the same HTTP response code and content as the original request.
For example, `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}` For example, [`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`](#put_matrixclientv3roomsroomidsendeventtypetxnid)
would return a `200 OK` with the `event_id` of the original request in would return a `200 OK` with the `event_id` of the original request in
the response body. the response body.
@ -897,7 +898,7 @@ follows:
``` ```
Note that `id_server` (and therefore `id_access_token`) is optional if Note that `id_server` (and therefore `id_access_token`) is optional if
the `/requestToken` request did not include them. the [`/requestToken`](#post_matrixclientv3registeremailrequesttoken) request did not include them.
##### Phone number/MSISDN-based (identity / homeserver) ##### Phone number/MSISDN-based (identity / homeserver)
@ -926,7 +927,7 @@ follows:
``` ```
Note that `id_server` (and therefore `id_access_token`) is optional if Note that `id_server` (and therefore `id_access_token`) is optional if
the `/requestToken` request did not include them. the [`/requestToken`](#post_matrixclientv3registermsisdnrequesttoken) request did not include them.
##### Dummy Auth ##### Dummy Auth
@ -1296,7 +1297,7 @@ from.
### Login ### Login
A client can obtain access tokens using the `/login` API. A client can obtain access tokens using the [`/login`](#post_matrixclientv3login) API.
Note that this endpoint does <span class="title-ref">not</span> Note that this endpoint does <span class="title-ref">not</span>
currently use the [User-Interactive Authentication currently use the [User-Interactive Authentication
@ -1554,7 +1555,7 @@ The capabilities advertised through this system are intended to
advertise functionality which is optional in the API, or which depend in advertise functionality which is optional in the API, or which depend in
some way on the state of the user or server. This system should not be some way on the state of the user or server. This system should not be
used to advertise unstable or experimental features - this is better used to advertise unstable or experimental features - this is better
done by the `/versions` endpoint. done by the [`/versions`](#get_matrixclientversions) endpoint.
Some examples of what a reasonable capability could be are: Some examples of what a reasonable capability could be are:
@ -1583,7 +1584,7 @@ specification are defined later in this section.
### `m.change_password` capability ### `m.change_password` capability
This capability has a single flag, `enabled`, which indicates whether or This capability has a single flag, `enabled`, which indicates whether or
not the user can use the `/account/password` API to change their not the user can use the [`/account/password`](#post_matrixclientv3accountpassword) API to change their
password. If not present, the client should assume that password changes password. If not present, the client should assume that password changes
are possible via the API. When present, clients SHOULD respect the are possible via the API. When present, clients SHOULD respect the
capability's `enabled` flag and indicate to the user if they are unable capability's `enabled` flag and indicate to the user if they are unable
@ -1765,16 +1766,17 @@ request with lazy-loading enabled, the server will only return
membership events for the `sender` of events in the timeline, not all membership events for the `sender` of events in the timeline, not all
members of a room. members of a room.
When processing a sequence of events (e.g. by looping on `/sync` or When processing a sequence of events (e.g. by looping on
paginating `/messages`), it is common for blocks of events in the [`/sync`](#get_matrixclientv3sync) or paginating
sequence to share a similar set of senders. Rather than responses in the [`/messages`](#get_matrixclientv3roomsroomidmessages)), it is common for blocks
sequence sending duplicate membership events for these senders to the of events in the sequence to share a similar set of senders. Rather than
client, the server MAY assume that clients will remember membership responses in the sequence sending duplicate membership events for these senders
events they have already been sent, and choose to skip sending to the client, the server MAY assume that clients will remember membership
membership events for members whose membership has not changed. These events they have already been sent, and choose to skip sending membership
are called 'redundant membership events'. Clients may request that events for members whose membership has not changed. These are called
redundant membership events are always included in responses by setting 'redundant membership events'. Clients may request that redundant membership
`include_redundant_members` to true in the filter. events are always included in responses by setting `include_redundant_members`
to true in the filter.
The expected pattern for using lazy-loading is currently: The expected pattern for using lazy-loading is currently:
@ -1789,7 +1791,7 @@ The expected pattern for using lazy-loading is currently:
incremental /sync responses. incremental /sync responses.
- Clients which do not support tab-completion may instead pull in - Clients which do not support tab-completion may instead pull in
profiles for arbitrary users (e.g. read receipts, typing profiles for arbitrary users (e.g. read receipts, typing
notifications) on demand by querying the room state or `/profile`. notifications) on demand by querying the room state or [`/profile`](#get_matrixclientv3profileuserid).
The current endpoints which support lazy-loading room members are: The current endpoints which support lazy-loading room members are:
@ -2351,7 +2353,7 @@ The endpoints where the server *should* include bundled aggregations are:
{{% boxes/note %}} {{% boxes/note %}}
The server is **not** required to return bundled aggregations on deprecated endpoints The server is **not** required to return bundled aggregations on deprecated endpoints
such as `/initialSync`. such as [`/initialSync`](#get_matrixclientv3roomsroomidinitialsync).
{{% /boxes/note %}} {{% /boxes/note %}}
While this functionality allows the client to see what was known to the server at the While this functionality allows the client to see what was known to the server at the
@ -2604,9 +2606,10 @@ this will have been just the API definition and nothing more (like invites).
If the join rules allow, external users to the room can `/knock` on it to If the join rules allow, external users to the room can `/knock` on it to
request permission to join. Users with appropriate permissions within the request permission to join. Users with appropriate permissions within the
room can then approve (`/invite`) or deny (`/kick`, `/ban`, or otherwise room can then approve ([`/invite`](#post_matrixclientv3roomsroomidinvite))
or deny ([`/kick`](#post_matrixclientv3roomsroomidkick), [`/ban`](#post_matrixclientv3roomsroomidban), or otherwise
set membership to `leave`) the knock. Knocks can be retracted by calling set membership to `leave`) the knock. Knocks can be retracted by calling
`/leave` or otherwise setting membership to `leave`. [`/leave`](#post_matrixclientv3roomsroomidleave) or otherwise setting membership to `leave`.
Users who are currently in the room, already invited, or banned cannot Users who are currently in the room, already invited, or banned cannot
knock on the room. knock on the room.
@ -2725,12 +2728,12 @@ with:
"user_id": "<user id to ban>", "user_id": "<user id to ban>",
"reason": "string: <reason for the ban>" "reason": "string: <reason for the ban>"
} }
```` ```
Banning a user adjusts the banned member's membership state to `ban`. Banning a user adjusts the banned member's membership state to `ban`.
Like with other membership changes, a user can directly adjust the Like with other membership changes, a user can directly adjust the
target member's state, by making a request to target member's state, by making a request to
`/rooms/<room id>/state/m.room.member/<user id>`: [`/rooms/<room id>/state/m.room.member/<user id>`](#put_matrixclientv3roomsroomidstateeventtypestatekey):
```json ```json
{ {

2
content/client-server-api/modules/account_data.md
View file

@ -16,7 +16,7 @@ data with the same `type`.
The client receives the account data as events in the `account_data` The client receives the account data as events in the `account_data`
sections of a [`/sync`](#get_matrixclientv3sync) response. sections of a [`/sync`](#get_matrixclientv3sync) response.
These events can also be received in a `/events` response or in the These events can also be received in a [`/events`](#get_matrixclientv3events) response or in the
`account_data` section of a room in a `/sync` response. `m.tag` events appearing in `account_data` section of a room in a `/sync` response. `m.tag` events appearing in
`/events` will have a `room_id` with the room the tags are for. `/events` will have a `room_id` with the room the tags are for.

2
content/client-server-api/modules/content_repo.md
View file

@ -206,6 +206,6 @@ HTML page. Therefore, there is no risk in trusting the user-defined content type
as long as the `Content-Disposition` is calculated based on that type. as long as the `Content-Disposition` is calculated based on that type.
Clients SHOULD NOT rely on servers returning `inline` rather than `attachment` Clients SHOULD NOT rely on servers returning `inline` rather than `attachment`
on `/download`. Server implementations might decide out of an abundance of on [`/download`](#get_matrixclientv1mediadownloadservernamemediaid). Server implementations might decide out of an abundance of
caution that all downloads are responded to with `attachment`, regardless of caution that all downloads are responded to with `attachment`, regardless of
content type - clients should not be surprised by this behaviour. content type - clients should not be surprised by this behaviour.

4
content/client-server-api/modules/ignore_users.md
View file

@ -13,10 +13,10 @@ and servers can implement the ignoring of users.
To ignore a user, effectively blocking them, the client should add the 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 target user to the `m.ignored_user_list` event in their account data
using [`/user/<user_id>/account_data/<type>`](/client-server-api/#put_matrixclientv3useruseridaccount_datatype). Once ignored, the client will no longer receive events sent by using [`/user/<user_id>/account_data/<type>`](#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 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 hide previous content sent by the newly ignored user or perform a new
`/sync` with no previous token. [`/sync`](#get_matrixclientv3sync) with no previous token.
Invites to new rooms by ignored users will not be sent to the client. Invites to new rooms by ignored users will not be sent to the client.
The server may optionally reject the invite on behalf of the client. The server may optionally reject the invite on behalf of the client.

4
content/client-server-api/modules/push.md
View file

@ -1044,7 +1044,7 @@ messages they have received.
##### Receiving notifications ##### Receiving notifications
Servers MUST include the number of unread notifications in a client's Servers MUST include the number of unread notifications in a client's
`/sync` stream, and MUST update it as it changes. Notifications are [`/sync`](#get_matrixclientv3sync) stream, and MUST update it as it changes. Notifications are
determined by the push rules which apply to an event. determined by the push rules which apply to an event.
For encrypted events, the homeserver has limited access to the event content For encrypted events, the homeserver has limited access to the event content
@ -1091,7 +1091,7 @@ users in the room (excluding the sender). This may result in:
* Generating a new number of unread notifications for the user. * Generating a new number of unread notifications for the user.
* Making a request to the configured push gateway. * Making a request to the configured push gateway.
The updated notification count from a new event MUST appear in the same `/sync` The updated notification count from a new event MUST appear in the same [`/sync`](#get_matrixclientv3sync)
response as the event itself. response as the event itself.
#### Push Gateway behaviour #### Push Gateway behaviour

2
content/client-server-api/modules/receipts.md
View file

@ -41,7 +41,7 @@ Threaded read receipts are discussed in further detail [below](#threaded-read-re
{{% changed-in v="1.4" %}} Altered to support threaded read receipts. {{% changed-in v="1.4" %}} Altered to support threaded read receipts.
In `/sync`, receipts are listed under the `ephemeral` array of events In [`/sync`](#get_matrixclientv3sync), receipts are listed under the `ephemeral` array of events
for a given room. New receipts that come down the event streams are for a given room. New receipts that come down the event streams are
deltas which update existing mappings. Clients should replace older deltas which update existing mappings. Clients should replace older
receipt acknowledgements based on `user_id`, `receipt_type`, and the receipt acknowledgements based on `user_id`, `receipt_type`, and the

2
content/client-server-api/modules/stickers.md
View file

@ -16,7 +16,7 @@ when the sticker image is clicked.
#### Events #### Events
Sticker events are received as a single `m.sticker` event in the Sticker events are received as a single `m.sticker` event in the
`timeline` section of a room, in a `/sync`. `timeline` section of a room, in a [`/sync`](#get_matrixclientv3sync).
{{% event event="m.sticker" %}} {{% event event="m.sticker" %}}

8
content/client-server-api/modules/third_party_invites.md
View file

@ -5,7 +5,7 @@ This module adds in support for inviting new members to a room where
their Matrix user ID is not known, instead addressing them by a third-party their Matrix user ID is not known, instead addressing them by a third-party
identifier such as an email address. There are two flows here; one identifier such as an email address. There are two flows here; one
if a Matrix user ID is known for the third-party identifier, and one if if a Matrix user ID is known for the third-party identifier, and one if
not. Either way, the client calls `/invite` with the details of the not. Either way, the client calls [`/invite`](#post_matrixclientv3roomsroomidinvite) with the details of the
third-party identifier. third-party identifier.
The homeserver asks the identity server whether a Matrix user ID is The homeserver asks the identity server whether a Matrix user ID is
@ -37,7 +37,7 @@ A client asks a server to invite a user by their third-party identifier.
#### Server behaviour #### Server behaviour
Upon receipt of an `/invite`, the server is expected to look up the Upon receipt of an [`/invite`](#post_matrixclientv3roomsroomidinvite), the server is expected to look up the
third-party identifier with the provided identity server. If the lookup third-party identifier with the provided identity server. If the lookup
yields a result for a Matrix User ID then the normal invite process can yields a result for a Matrix User ID then the normal invite process can
be initiated. This process ends up looking like this: be initiated. This process ends up looking like this:
@ -186,9 +186,9 @@ residents of the room while H3 is attempting to join.
Note that when H1 sends the `m.room.member` event to H2 and H3 it does Note that when H1 sends the `m.room.member` event to H2 and H3 it does
not have to block on either server's receipt of the event. Likewise, H1 not have to block on either server's receipt of the event. Likewise, H1
may complete the `/exchange_third_party_invite/:roomId` request at the may complete the [`/exchange_third_party_invite`](/server-server-api/#put_matrixfederationv1exchange_third_party_inviteroomid) request at the
same time as sending the `m.room.member` event to H2 and H3. same time as sending the `m.room.member` event to H2 and H3.
Additionally, H3 may complete the `/3pid/onbind` request it got from IS Additionally, H3 may complete the [`/3pid/onbind`](/server-server-api/#put_matrixfederationv13pidonbind) request it got from IS
at any time - the completion is not shown in the diagram. at any time - the completion is not shown in the diagram.
H1 MUST verify the request from H3 to ensure the `signed` property is H1 MUST verify the request from H3 to ensure the `signed` property is