From 9cff8a2707ed7777b03b1f32af5fa898f8588ea2 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 26 Nov 2024 22:29:47 +0000 Subject: [PATCH] Add hyperlinks to endpoints ... because there's nothing more infuriating than someone talking about an endpoint, then having to search through 150 pages of spec for it. --- .../newsfragments/2016.clarification | 1 + content/client-server-api/_index.md | 55 ++++++++++--------- .../client-server-api/modules/account_data.md | 2 +- .../client-server-api/modules/content_repo.md | 2 +- .../client-server-api/modules/ignore_users.md | 4 +- content/client-server-api/modules/push.md | 4 +- content/client-server-api/modules/receipts.md | 2 +- content/client-server-api/modules/stickers.md | 2 +- .../modules/third_party_invites.md | 8 +-- 9 files changed, 42 insertions(+), 38 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2016.clarification diff --git a/changelogs/client_server/newsfragments/2016.clarification b/changelogs/client_server/newsfragments/2016.clarification new file mode 100644 index 000000000..34aa3b222 --- /dev/null +++ b/changelogs/client_server/newsfragments/2016.clarification @@ -0,0 +1 @@ +Add hyperlinks throughout the specification. diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index bfcbd031d..3f37ea7f9 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -29,7 +29,7 @@ JSON object. Clients should supply a `Content-Type` header of The exceptions are: -- [`POST /_matrix/media/v3/upload`](#post_matrixmediav3upload) and +- [`POST /_matrix/media/v3/upload`](#post_matrixmediav3upload) and [`PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`](#put_matrixmediav3uploadservernamemediaid), both of which take the uploaded media as the request body. - [`POST /_matrix/client/v3/logout`](#post_matrixclientv3logout) and @@ -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 not currently use the [User-Interactive Authentication @@ -1471,7 +1472,7 @@ Content-Type: application/json ``` Servers SHOULD NOT invalidate access tokens on locked accounts unless the -client requests a logout (using the above endpoints). This ensures that +client requests a logout (using the above endpoints). This ensures that users can retain their sessions without having to log back in if the account becomes unlocked. @@ -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 @@ -1764,16 +1765,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: @@ -1788,7 +1790,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: @@ -2350,7 +2352,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 @@ -2603,9 +2605,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. @@ -2724,12 +2727,12 @@ with: "user_id": "", "reason": "string: " } -```` +``` 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//state/m.room.member/`: +[`/rooms//state/m.room.member/`](#put_matrixclientv3roomsroomidstateeventtypestatekey): ```json { diff --git a/content/client-server-api/modules/account_data.md b/content/client-server-api/modules/account_data.md index 3068602de..1f1e5b8c0 100644 --- a/content/client-server-api/modules/account_data.md +++ b/content/client-server-api/modules/account_data.md @@ -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. diff --git a/content/client-server-api/modules/content_repo.md b/content/client-server-api/modules/content_repo.md index a3e38b43c..c70d04fc2 100644 --- a/content/client-server-api/modules/content_repo.md +++ b/content/client-server-api/modules/content_repo.md @@ -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. diff --git a/content/client-server-api/modules/ignore_users.md b/content/client-server-api/modules/ignore_users.md index f682d9e65..f87beccf6 100644 --- a/content/client-server-api/modules/ignore_users.md +++ b/content/client-server-api/modules/ignore_users.md @@ -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//account_data/`](/client-server-api/#put_matrixclientv3useruseridaccount_datatype). Once ignored, the client will no longer receive events sent by +using [`/user//account_data/`](#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. diff --git a/content/client-server-api/modules/push.md b/content/client-server-api/modules/push.md index 3b256f012..156399952 100644 --- a/content/client-server-api/modules/push.md +++ b/content/client-server-api/modules/push.md @@ -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 diff --git a/content/client-server-api/modules/receipts.md b/content/client-server-api/modules/receipts.md index 877103feb..f38e8611c 100644 --- a/content/client-server-api/modules/receipts.md +++ b/content/client-server-api/modules/receipts.md @@ -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 diff --git a/content/client-server-api/modules/stickers.md b/content/client-server-api/modules/stickers.md index 32edaacc5..0125dd884 100644 --- a/content/client-server-api/modules/stickers.md +++ b/content/client-server-api/modules/stickers.md @@ -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" %}} diff --git a/content/client-server-api/modules/third_party_invites.md b/content/client-server-api/modules/third_party_invites.md index 7e418e153..9ac55f57b 100644 --- a/content/client-server-api/modules/third_party_invites.md +++ b/content/client-server-api/modules/third_party_invites.md @@ -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