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`
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`
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.
Typically, this error will appear on routes which attempt to modify
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`
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
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
the response body.
@ -897,7 +898,7 @@ follows:
```
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)
@ -926,7 +927,7 @@ follows:
```
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
@ -1296,7 +1297,7 @@ from.
### 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>
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
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
done by the `/versions` endpoint.
done by the [`/versions`](#get_matrixclientversions) endpoint.
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
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
are possible via the API. When present, clients SHOULD respect the
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
members of a room.
When processing a sequence of events (e.g. by looping on `/sync` or
paginating `/messages`), it is common for blocks of events in the
sequence to share a similar set of senders. Rather than responses in the
sequence sending duplicate membership events for these senders to the
client, the server MAY assume that clients will remember membership
events they have already been sent, and choose to skip sending
membership events for members whose membership has not changed. These
are called 'redundant membership events'. Clients may request that
redundant membership events are always included in responses by setting
`include_redundant_members` to true in the filter.
When processing a sequence of events (e.g. by looping on
[`/sync`](#get_matrixclientv3sync) or paginating
[`/messages`](#get_matrixclientv3roomsroomidmessages)), it is common for blocks
of events in the sequence to share a similar set of senders. Rather than
responses in the sequence sending duplicate membership events for these senders
to the client, the server MAY assume that clients will remember membership
events they have already been sent, and choose to skip sending membership
events for members whose membership has not changed. These are called
'redundant membership events'. Clients may request that redundant membership
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:
@ -1789,7 +1791,7 @@ The expected pattern for using lazy-loading is currently:
incremental /sync responses.
- Clients which do not support tab-completion may instead pull in
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:
@ -2351,7 +2353,7 @@ The endpoints where the server *should* include bundled aggregations are:
{{% boxes/note %}}
The server is **not** required to return bundled aggregations on deprecated endpoints
such as `/initialSync`.
such as [`/initialSync`](#get_matrixclientv3roomsroomidinitialsync).
{{% /boxes/note %}}
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
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
`/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
knock on the room.
@ -2725,12 +2728,12 @@ with:
"user_id": "<user id to ban>",
"reason": "string: <reason for the ban>"
}
````
```
Banning a user adjusts the banned member's membership state to `ban`.
Like with other membership changes, a user can directly adjust the
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
{

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`
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
`/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.
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
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
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
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.
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
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.
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.
* 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.
#### 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.
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
deltas which update existing mappings. Clients should replace older
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
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" %}}

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
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
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.
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
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
yields a result for a Matrix User ID then the normal invite process can
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
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.
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.
H1 MUST verify the request from H3 to ensure the `signed` property is