From 95d850c418ee544a25ee33c19c8fd65deedbf868 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 12 Oct 2021 11:07:01 -0600 Subject: [PATCH] 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 --- .../client_server/newsfragments/3421.feature | 1 + content/application-service-api.md | 8 ++-- content/client-server-api/_index.md | 32 ++++++------- content/client-server-api/modules/dm.md | 8 ++-- .../modules/end_to_end_encryption.md | 48 +++++++++---------- .../client-server-api/modules/guest_access.md | 42 ++++++++-------- .../client-server-api/modules/ignore_users.md | 2 +- content/client-server-api/modules/push.md | 46 +++++++++--------- .../modules/room_previews.md | 10 ++-- .../modules/send_to_device.md | 10 ++-- .../client-server-api/modules/sso_login.md | 30 ++++++------ data/api/client-server/account-data.yaml | 2 +- data/api/client-server/admin.yaml | 2 +- .../client-server/administrative_contact.yaml | 6 +-- .../appservice_room_directory.yaml | 2 +- data/api/client-server/banning.yaml | 2 +- data/api/client-server/capabilities.yaml | 2 +- data/api/client-server/content-repo.yaml | 2 +- data/api/client-server/create_room.yaml | 2 +- data/api/client-server/cross_signing.yaml | 2 +- .../definitions/timeline_batch.yaml | 2 +- data/api/client-server/device_management.yaml | 2 +- data/api/client-server/directory.yaml | 2 +- data/api/client-server/event_context.yaml | 2 +- data/api/client-server/filter.yaml | 2 +- data/api/client-server/inviting.yaml | 4 +- data/api/client-server/joining.yaml | 10 ++-- data/api/client-server/key_backup.yaml | 12 ++--- data/api/client-server/keys.yaml | 6 +-- data/api/client-server/kicking.yaml | 2 +- data/api/client-server/knocking.yaml | 4 +- data/api/client-server/leaving.yaml | 2 +- data/api/client-server/list_joined_rooms.yaml | 2 +- data/api/client-server/list_public_rooms.yaml | 2 +- data/api/client-server/login.yaml | 2 +- data/api/client-server/logout.yaml | 2 +- .../api/client-server/message_pagination.yaml | 4 +- data/api/client-server/notifications.yaml | 2 +- data/api/client-server/old_sync.yaml | 14 +++--- data/api/client-server/openid.yaml | 2 +- data/api/client-server/peeking_events.yaml | 2 +- data/api/client-server/presence.yaml | 2 +- data/api/client-server/profile.yaml | 2 +- data/api/client-server/pusher.yaml | 2 +- data/api/client-server/pushrules.yaml | 2 +- data/api/client-server/read_markers.yaml | 2 +- data/api/client-server/receipts.yaml | 2 +- data/api/client-server/redaction.yaml | 2 +- data/api/client-server/registration.yaml | 6 +-- data/api/client-server/report_content.yaml | 2 +- data/api/client-server/room_initial_sync.yaml | 8 ++-- data/api/client-server/room_send.yaml | 2 +- data/api/client-server/room_state.yaml | 2 +- data/api/client-server/room_upgrades.yaml | 2 +- data/api/client-server/rooms.yaml | 2 +- data/api/client-server/search.yaml | 2 +- .../api/client-server/sso_login_redirect.yaml | 2 +- data/api/client-server/sync.yaml | 2 +- data/api/client-server/tags.yaml | 2 +- .../api/client-server/third_party_lookup.yaml | 4 +- .../client-server/third_party_membership.yaml | 4 +- data/api/client-server/to_device.yaml | 2 +- data/api/client-server/typing.yaml | 2 +- data/api/client-server/users.yaml | 2 +- data/api/client-server/voip.yaml | 2 +- data/api/client-server/whoami.yaml | 2 +- layouts/shortcodes/http-api.html | 2 +- openapi_extensions.md | 6 +-- scripts/dump-swagger.py | 3 -- 69 files changed, 206 insertions(+), 210 deletions(-) create mode 100644 changelogs/client_server/newsfragments/3421.feature diff --git a/changelogs/client_server/newsfragments/3421.feature b/changelogs/client_server/newsfragments/3421.feature new file mode 100644 index 00000000..7f223c24 --- /dev/null +++ b/changelogs/client_server/newsfragments/3421.feature @@ -0,0 +1 @@ +Re-version all endpoints to be `v3` as a starting point instead of `r0` as per [MSC2844](https://github.com/matrix-org/matrix-doc/pull/2844). diff --git a/content/application-service-api.md b/content/application-service-api.md index e324bba0..c15251ab 100644 --- a/content/application-service-api.md +++ b/content/application-service-api.md @@ -271,11 +271,11 @@ should identify itself to the Client-Server API by providing its `as_token` for the `access_token` alongside the user the application service would like to masquerade as. -Inputs: +Inputs: - Application service token (`as_token`) - User ID in the AS namespace to act as. -Notes: +Notes: - This applies to all aspects of the Client-Server API, except for Account Management. - The `as_token` is inserted into `access_token` which is usually @@ -295,7 +295,7 @@ by the `sender_localpart` property of the registration. An example request would be: - GET /_matrix/client/%CLIENT_MAJOR_VERSION%/account/whoami?user_id=@_irc_user:example.org + GET /_matrix/client/v3/account/whoami?user_id=@_irc_user:example.org Authorization: Bearer YourApplicationServiceTokenHere #### Timestamp massaging @@ -325,7 +325,7 @@ achieved by including the `as_token` on a `/register` request, along with a login type of `m.login.application_service` to set the desired user ID without a password. - POST /_matrix/client/%CLIENT_MAJOR_VERSION%/register + POST /_matrix/client/v3/register Authorization: Bearer YourApplicationServiceTokenHere Content: diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index f868509b..98bf2be0 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -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//fallback/web?session= + /_matrix/client/v3/auth//fallback/web?session= 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//messages`](/client-server-api/#get_matrixclientr0roomsroomidmessages) -- [`/rooms/{roomId}/context/{eventId}`](/client-server-api/#get_matrixclientr0roomsroomidcontexteventid) +- [`/sync`](/client-server-api/#get_matrixclientv3sync) +- [`/rooms//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//messages`](/client-server-api/#get_matrixclientr0roomsroomidmessages) API to retrieve earlier +parameter to the [`/rooms//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//messages`](/client-server-api/#get_matrixclientr0roomsroomidmessages) API. This situation looks like this: +[`/rooms//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//ban`](/client-server-api/#post_matrixclientr0roomsroomidban) +To ban a user, a request should be made to [`/rooms//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//unban`](/client-server-api/#post_matrixclientr0roomsroomidunban) before they can re-join the room or be +[`/rooms//unban`](/client-server-api/#post_matrixclientv3roomsroomidunban) before they can re-join the room or be re-invited. {{% http-api spec="client-server" api="banning" %}} diff --git a/content/client-server-api/modules/dm.md b/content/client-server-api/modules/dm.md index 59d09e3e..bd68a4dd 100644 --- a/content/client-server-api/modules/dm.md +++ b/content/client-server-api/modules/dm.md @@ -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//account_data/`](/client-server-api/#put_matrixclientr0useruseridaccount_datatype). +account data using [`/user//account_data/`](/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. diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md index 9a109163..f1d4e91c 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -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 | |----------------------------|--------------------|------------------------------------------------------------------------------------------------------------------------| diff --git a/content/client-server-api/modules/guest_access.md b/content/client-server-api/modules/guest_access.md index 7d04035e..3805b369 100644 --- a/content/client-server-api/modules/guest_access.md +++ b/content/client-server-api/modules/guest_access.md @@ -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 diff --git a/content/client-server-api/modules/ignore_users.md b/content/client-server-api/modules/ignore_users.md index b67f5976..1b7282fc 100644 --- a/content/client-server-api/modules/ignore_users.md +++ b/content/client-server-api/modules/ignore_users.md @@ -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//account_data/`](/client-server-api/#put_matrixclientr0useruseridaccount_datatype). Once ignored, the client will no longer receive events sent by +using [`/user//account_data/`](/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. diff --git a/content/client-server-api/modules/push.md b/content/client-server-api/modules/push.md index e98d7eda..0f7c7eeb 100644 --- a/content/client-server-api/modules/push.md +++ b/content/client-server-api/modules/push.md @@ -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" }, diff --git a/content/client-server-api/modules/room_previews.md b/content/client-server-api/modules/room_previews.md index ecaedcbd..5e31b647 100644 --- a/content/client-server-api/modules/room_previews.md +++ b/content/client-server-api/modules/room_previews.md @@ -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" %}} diff --git a/content/client-server-api/modules/send_to_device.md b/content/client-server-api/modules/send_to_device.md index 16ce3e46..5758fa01 100644 --- a/content/client-server-api/modules/send_to_device.md +++ b/content/client-server-api/modules/send_to_device.md @@ -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//send`](/client-server-api/#put_matrixclientr0roomsroomidsendeventtypetxnid) API for +conversational data, which should be sent using the normal [`/rooms//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 | |-----------|-----------|-----------------------------------------------------------------------------| diff --git a/content/client-server-api/modules/sso_login.md b/content/client-server-api/modules/sso_login.md index 2bc3916b..3318aea0 100644 --- a/content/client-server-api/modules/sso_login.md +++ b/content/client-server-api/modules/sso_login.md @@ -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=`. +`/_matrix/client/v3/auth/m.login.sso/fallback/web?session=`. 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. diff --git a/data/api/client-server/account-data.yaml b/data/api/client-server/account-data.yaml index ec0d017f..89c2f220 100644 --- a/data/api/client-server/account-data.yaml +++ b/data/api/client-server/account-data.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/admin.yaml b/data/api/client-server/admin.yaml index 8794a65c..403be39f 100644 --- a/data/api/client-server/admin.yaml +++ b/data/api/client-server/admin.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/administrative_contact.yaml b/data/api/client-server/administrative_contact.yaml index e6e1267b..84c24a9f 100644 --- a/data/api/client-server/administrative_contact.yaml +++ b/data/api/client-server/administrative_contact.yaml @@ -20,7 +20,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: @@ -427,7 +427,7 @@ paths: already associated with an account on this homeserver. This API should be used to request validation tokens when adding an email address to an account. This API's parameters and response are identical to that of - the [`/register/email/requestToken`](/client-server-api/#post_matrixclientr0registeremailrequesttoken) + the [`/register/email/requestToken`](/client-server-api/#post_matrixclientv3registeremailrequesttoken) endpoint. The homeserver should validate the email itself, either by sending a validation email itself or by using a service it has control over. @@ -480,7 +480,7 @@ paths: already associated with an account on this homeserver. This API should be used to request validation tokens when adding a phone number to an account. This API's parameters and response are identical to that of - the [`/register/msisdn/requestToken`](/client-server-api/#post_matrixclientr0registermsisdnrequesttoken) + the [`/register/msisdn/requestToken`](/client-server-api/#post_matrixclientv3registermsisdnrequesttoken) endpoint. The homeserver should validate the phone number itself, either by sending a validation message itself or by using a service it has control over. diff --git a/data/api/client-server/appservice_room_directory.yaml b/data/api/client-server/appservice_room_directory.yaml index ab66bdd9..233bf2bd 100644 --- a/data/api/client-server/appservice_room_directory.yaml +++ b/data/api/client-server/appservice_room_directory.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/banning.yaml b/data/api/client-server/banning.yaml index 5c6e7ee3..f9dee911 100644 --- a/data/api/client-server/banning.yaml +++ b/data/api/client-server/banning.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml index ece0d9ad..d31d01d7 100644 --- a/data/api/client-server/capabilities.yaml +++ b/data/api/client-server/capabilities.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 produces: - application/json securityDefinitions: diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml index fb91c7c5..f614f9c7 100644 --- a/data/api/client-server/content-repo.yaml +++ b/data/api/client-server/content-repo.yaml @@ -20,7 +20,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/media/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/media/v3 consumes: - application/json - "*/*" diff --git a/data/api/client-server/create_room.yaml b/data/api/client-server/create_room.yaml index 207c8620..c5369108 100644 --- a/data/api/client-server/create_room.yaml +++ b/data/api/client-server/create_room.yaml @@ -20,7 +20,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/cross_signing.yaml b/data/api/client-server/cross_signing.yaml index 3c17cd11..721f6344 100644 --- a/data/api/client-server/cross_signing.yaml +++ b/data/api/client-server/cross_signing.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/definitions/timeline_batch.yaml b/data/api/client-server/definitions/timeline_batch.yaml index 35632562..23f175fb 100644 --- a/data/api/client-server/definitions/timeline_batch.yaml +++ b/data/api/client-server/definitions/timeline_batch.yaml @@ -21,7 +21,7 @@ properties: type: boolean prev_batch: description: A token that can be supplied to the `from` parameter of the - [`/rooms//messages`](#get_matrixclientr0roomsroomidmessages) + [`/rooms//messages`](#get_matrixclientv3roomsroomidmessages) endpoint in order to retrieve earlier events. If no earlier events are available, this property may be omitted from diff --git a/data/api/client-server/device_management.yaml b/data/api/client-server/device_management.yaml index aeb1346a..84e5ee23 100644 --- a/data/api/client-server/device_management.yaml +++ b/data/api/client-server/device_management.yaml @@ -20,7 +20,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/directory.yaml b/data/api/client-server/directory.yaml index 1b01242d..1b128905 100644 --- a/data/api/client-server/directory.yaml +++ b/data/api/client-server/directory.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/event_context.yaml b/data/api/client-server/event_context.yaml index 03e38fe1..689e998c 100644 --- a/data/api/client-server/event_context.yaml +++ b/data/api/client-server/event_context.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/filter.yaml b/data/api/client-server/filter.yaml index 0a12e2bb..d5575ff5 100644 --- a/data/api/client-server/filter.yaml +++ b/data/api/client-server/filter.yaml @@ -18,7 +18,7 @@ info: host: localhost:8008 schemes: - https -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/inviting.yaml b/data/api/client-server/inviting.yaml index b099b3ef..0e223fa7 100644 --- a/data/api/client-server/inviting.yaml +++ b/data/api/client-server/inviting.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: @@ -36,7 +36,7 @@ paths: *Note that there are two forms of this API, which are documented separately. This version of the API requires that the inviter knows the Matrix identifier of the invitee. The other is documented in the* - [third party invites section](/client-server-api/#post_matrixclientr0roomsroomidinvite-1). + [third party invites section](/client-server-api/#post_matrixclientv3roomsroomidinvite-1). This API invites a user to participate in a particular room. They do not start participating in the room until they actually join the diff --git a/data/api/client-server/joining.yaml b/data/api/client-server/joining.yaml index e56d6ada..0fe5164d 100644 --- a/data/api/client-server/joining.yaml +++ b/data/api/client-server/joining.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: @@ -40,8 +40,8 @@ paths: events associated with the room until the user leaves the room. After a user has joined a room, the room will appear as an entry in the - response of the [`/initialSync`](/client-server-api/#get_matrixclientr0initialsync) - and [`/sync`](/client-server-api/#get_matrixclientr0sync) APIs. + response of the [`/initialSync`](/client-server-api/#get_matrixclientv3initialsync) + and [`/sync`](/client-server-api/#get_matrixclientv3sync) APIs. operationId: joinRoomById security: - accessToken: [] @@ -117,8 +117,8 @@ paths: events associated with the room until the user leaves the room. After a user has joined a room, the room will appear as an entry in the - response of the [`/initialSync`](/client-server-api/#get_matrixclientr0initialsync) - and [`/sync`](/client-server-api/#get_matrixclientr0sync) APIs. + response of the [`/initialSync`](/client-server-api/#get_matrixclientv3initialsync) + and [`/sync`](/client-server-api/#get_matrixclientv3sync) APIs. operationId: joinRoom security: - accessToken: [] diff --git a/data/api/client-server/key_backup.yaml b/data/api/client-server/key_backup.yaml index 43851791..6e788908 100644 --- a/data/api/client-server/key_backup.yaml +++ b/data/api/client-server/key_backup.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: @@ -170,7 +170,7 @@ paths: description: |- The backup version to get, as returned in the `version` parameter of the response in - [`POST /_matrix/client/r0/room_keys/version`](/client-server/#post_matrixclientr0room_keysversion) + [`POST /_matrix/client/r0/room_keys/version`](/client-server/#post_matrixclientv3room_keysversion) or this endpoint. required: true x-example: "1" @@ -252,8 +252,8 @@ paths: description: |- The backup version to update, as returned in the `version` parameter in the response of - [`POST /_matrix/client/r0/room_keys/version`](/client-server-api/#post_matrixclientr0room_keysversion) - or [`GET /_matrix/client/r0/room_keys/version/{version}`](/client-server-api/#get_matrixclientr0room_keysversionversion). + [`POST /_matrix/client/r0/room_keys/version`](/client-server-api/#post_matrixclientv3room_keysversion) + or [`GET /_matrix/client/r0/room_keys/version/{version}`](/client-server-api/#get_matrixclientv3room_keysversionversion). required: true x-example: "1" - in: body @@ -341,8 +341,8 @@ paths: description: |- The backup version to delete, as returned in the `version` parameter in the response of - [`POST /_matrix/client/r0/room_keys/version`](/client-server-api/#post_matrixclientr0room_keysversion) - or [`GET /_matrix/client/r0/room_keys/version/{version}`](/client-server-api/#get_matrixclientr0room_keysversionversion). + [`POST /_matrix/client/r0/room_keys/version`](/client-server-api/#post_matrixclientv3room_keysversion) + or [`GET /_matrix/client/r0/room_keys/version/{version}`](/client-server-api/#get_matrixclientv3room_keysversionversion). required: true x-example: "1" responses: diff --git a/data/api/client-server/keys.yaml b/data/api/client-server/keys.yaml index e0788b6b..26a10aed 100644 --- a/data/api/client-server/keys.yaml +++ b/data/api/client-server/keys.yaml @@ -21,7 +21,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: @@ -437,7 +437,7 @@ paths: type: string description: |- The desired start point of the list. Should be the `next_batch` field - from a response to an earlier call to [`/sync`](/client-server-api/#get_matrixclientr0sync). Users who have not + from a response to an earlier call to [`/sync`](/client-server-api/#get_matrixclientv3sync). Users who have not uploaded new device identity keys since this point, nor deleted existing devices with identity keys since then, will be excluded from the results. @@ -448,7 +448,7 @@ paths: type: string description: |- The desired end point of the list. Should be the `next_batch` - field from a recent call to [`/sync`](/client-server-api/#get_matrixclientr0sync) - typically the most recent + field from a recent call to [`/sync`](/client-server-api/#get_matrixclientv3sync) - typically the most recent such call. This may be used by the server as a hint to check its caches are up to date. required: true diff --git a/data/api/client-server/kicking.yaml b/data/api/client-server/kicking.yaml index bf6738e1..c0d8f671 100644 --- a/data/api/client-server/kicking.yaml +++ b/data/api/client-server/kicking.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/knocking.yaml b/data/api/client-server/knocking.yaml index 0db92d5e..2c663144 100644 --- a/data/api/client-server/knocking.yaml +++ b/data/api/client-server/knocking.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: @@ -45,7 +45,7 @@ paths: history visibility to the user. The knock will appear as an entry in the response of the - [`/sync`](/client-server-api/#get_matrixclientr0sync) API. + [`/sync`](/client-server-api/#get_matrixclientv3sync) API. operationId: knockRoom security: - accessToken: [] diff --git a/data/api/client-server/leaving.yaml b/data/api/client-server/leaving.yaml index f3d3b486..caed647b 100644 --- a/data/api/client-server/leaving.yaml +++ b/data/api/client-server/leaving.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/list_joined_rooms.yaml b/data/api/client-server/list_joined_rooms.yaml index b34f3d5d..177949bf 100644 --- a/data/api/client-server/list_joined_rooms.yaml +++ b/data/api/client-server/list_joined_rooms.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/list_public_rooms.yaml b/data/api/client-server/list_public_rooms.yaml index 87806e04..fd776b52 100644 --- a/data/api/client-server/list_public_rooms.yaml +++ b/data/api/client-server/list_public_rooms.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/login.yaml b/data/api/client-server/login.yaml index 14aa3aaf..8865665f 100644 --- a/data/api/client-server/login.yaml +++ b/data/api/client-server/login.yaml @@ -20,7 +20,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/logout.yaml b/data/api/client-server/logout.yaml index 7be4f51c..ad809de0 100644 --- a/data/api/client-server/logout.yaml +++ b/data/api/client-server/logout.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/message_pagination.yaml b/data/api/client-server/message_pagination.yaml index c3c8d888..4d2631da 100644 --- a/data/api/client-server/message_pagination.yaml +++ b/data/api/client-server/message_pagination.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: @@ -55,7 +55,7 @@ paths: or from an `end` token returned by a previous request to this endpoint. This endpoint can also accept a value returned as a `start` token - by a previous request to this endpoint, though servers are not + by a previous request to this endpoint, though servers are not required to support this. Clients should not rely on the behaviour. required: true x-example: "s345_678_333" diff --git a/data/api/client-server/notifications.yaml b/data/api/client-server/notifications.yaml index 0176a9b4..729873bb 100644 --- a/data/api/client-server/notifications.yaml +++ b/data/api/client-server/notifications.yaml @@ -20,7 +20,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/old_sync.yaml b/data/api/client-server/old_sync.yaml index d961077b..57305416 100644 --- a/data/api/client-server/old_sync.yaml +++ b/data/api/client-server/old_sync.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: @@ -35,7 +35,7 @@ paths: block until an event is received, or until the `timeout` is reached. This endpoint was deprecated in r0 of this specification. Clients - should instead call the [`/sync`](/client-server-api/#get_matrixclientr0sync) + should instead call the [`/sync`](/client-server-api/#get_matrixclientv3sync) endpoint with a `since` parameter. See the [migration guide](https://matrix.org/docs/guides/migrating-from-client-server-api-v-1#deprecated-endpoints). operationId: getEvents @@ -101,7 +101,7 @@ paths: number of messages per room to return. This endpoint was deprecated in r0 of this specification. Clients - should instead call the [`/sync`](/client-server-api/#get_matrixclientr0sync) + should instead call the [`/sync`](/client-server-api/#get_matrixclientv3sync) endpoint with no `since` parameter. See the [migration guide](https://matrix.org/docs/guides/migrating-from-client-server-api-v-1#deprecated-endpoints). operationId: initialSync @@ -239,7 +239,7 @@ paths: description: |- A token which correlates to the start of `chunk`. Can be passed to - [`/rooms//messages`](#get_matrixclientr0roomsroomidmessages) + [`/rooms//messages`](#get_matrixclientv3roomsroomidmessages) to retrieve earlier events. If no earlier events are available, this property may be omitted from @@ -249,7 +249,7 @@ paths: description: |- A token which correlates to the end of `chunk`. Can be passed to - [`/rooms//messages`](#get_matrixclientr0roomsroomidmessages) + [`/rooms//messages`](#get_matrixclientv3roomsroomidmessages) to retrieve later events. chunk: type: array @@ -318,8 +318,8 @@ paths: This endpoint was deprecated in r0 of this specification. Clients should instead call the - [/rooms/{roomId}/event/{eventId}](/client-server-api/#get_matrixclientr0roomsroomideventeventid) API - or the [/rooms/{roomId}/context/{eventId](/client-server-api/#get_matrixclientr0roomsroomidcontexteventid) API. + [/rooms/{roomId}/event/{eventId}](/client-server-api/#get_matrixclientv3roomsroomideventeventid) API + or the [/rooms/{roomId}/context/{eventId](/client-server-api/#get_matrixclientv3roomsroomidcontexteventid) API. operationId: getOneEvent security: - accessToken: [] diff --git a/data/api/client-server/openid.yaml b/data/api/client-server/openid.yaml index ef76e3d0..a6adeb7f 100644 --- a/data/api/client-server/openid.yaml +++ b/data/api/client-server/openid.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/peeking_events.yaml b/data/api/client-server/peeking_events.yaml index 0bf303ef..8f87a28a 100644 --- a/data/api/client-server/peeking_events.yaml +++ b/data/api/client-server/peeking_events.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/presence.yaml b/data/api/client-server/presence.yaml index 003de8ca..6d144db2 100644 --- a/data/api/client-server/presence.yaml +++ b/data/api/client-server/presence.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml index d1d4306c..e0a4c50d 100644 --- a/data/api/client-server/profile.yaml +++ b/data/api/client-server/profile.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/pusher.yaml b/data/api/client-server/pusher.yaml index 9feccb4f..ec46c353 100644 --- a/data/api/client-server/pusher.yaml +++ b/data/api/client-server/pusher.yaml @@ -20,7 +20,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/pushrules.yaml b/data/api/client-server/pushrules.yaml index 9a595271..5432df54 100644 --- a/data/api/client-server/pushrules.yaml +++ b/data/api/client-server/pushrules.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/read_markers.yaml b/data/api/client-server/read_markers.yaml index aa9d0ecb..ccfd0657 100644 --- a/data/api/client-server/read_markers.yaml +++ b/data/api/client-server/read_markers.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/receipts.yaml b/data/api/client-server/receipts.yaml index 66610092..df720cbd 100644 --- a/data/api/client-server/receipts.yaml +++ b/data/api/client-server/receipts.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/redaction.yaml b/data/api/client-server/redaction.yaml index aeef07a5..37ff9741 100644 --- a/data/api/client-server/redaction.yaml +++ b/data/api/client-server/redaction.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/registration.yaml b/data/api/client-server/registration.yaml index 526233fa..810d8bc9 100644 --- a/data/api/client-server/registration.yaml +++ b/data/api/client-server/registration.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: @@ -393,7 +393,7 @@ paths: `/account/password` endpoint. This API's parameters and response are identical to that of the - [`/register/email/requestToken`](/client-server-api/#post_matrixclientr0registeremailrequesttoken) + [`/register/email/requestToken`](/client-server-api/#post_matrixclientv3registeremailrequesttoken) endpoint, except that `M_THREEPID_NOT_FOUND` may be returned if no account matching the given email address could be found. The server may instead send an @@ -450,7 +450,7 @@ paths: `/account/password` endpoint. This API's parameters and response are identical to that of the - [`/register/msisdn/requestToken`](/client-server-api/#post_matrixclientr0registermsisdnrequesttoken) + [`/register/msisdn/requestToken`](/client-server-api/#post_matrixclientv3registermsisdnrequesttoken) endpoint, except that `M_THREEPID_NOT_FOUND` may be returned if no account matching the given phone number could be found. The server may instead send the SMS diff --git a/data/api/client-server/report_content.yaml b/data/api/client-server/report_content.yaml index 19d6b6d0..7f8b3425 100644 --- a/data/api/client-server/report_content.yaml +++ b/data/api/client-server/report_content.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/room_initial_sync.yaml b/data/api/client-server/room_initial_sync.yaml index f8660e69..aa028a16 100644 --- a/data/api/client-server/room_initial_sync.yaml +++ b/data/api/client-server/room_initial_sync.yaml @@ -6,7 +6,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: @@ -22,7 +22,7 @@ paths: This endpoint was deprecated in r0 of this specification. There is no direct replacement; the relevant information is returned by the - [`/sync`](/client-server-api/#get_matrixclientr0sync) API. See the + [`/sync`](/client-server-api/#get_matrixclientv3sync) API. See the [migration guide](https://matrix.org/docs/guides/migrating-from-client-server-api-v-1#deprecated-endpoints). operationId: roomInitialSync security: @@ -99,7 +99,7 @@ paths: type: string description: |- A token which correlates to the start of `chunk`. Can be passed to - [`/rooms//messages`](#get_matrixclientr0roomsroomidmessages) + [`/rooms//messages`](#get_matrixclientv3roomsroomidmessages) to retrieve earlier events. If no earlier events are available, this property may be omitted from @@ -108,7 +108,7 @@ paths: type: string description: |- A token which correlates to the end of `chunk`. Can be passed to - [`/rooms//messages`](#get_matrixclientr0roomsroomidmessages) + [`/rooms//messages`](#get_matrixclientv3roomsroomidmessages) to retrieve later events. chunk: type: array diff --git a/data/api/client-server/room_send.yaml b/data/api/client-server/room_send.yaml index 18658f61..28591a3a 100644 --- a/data/api/client-server/room_send.yaml +++ b/data/api/client-server/room_send.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/room_state.yaml b/data/api/client-server/room_state.yaml index 016a8273..89792e63 100644 --- a/data/api/client-server/room_state.yaml +++ b/data/api/client-server/room_state.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/room_upgrades.yaml b/data/api/client-server/room_upgrades.yaml index 97ef611e..41b3a7af 100644 --- a/data/api/client-server/room_upgrades.yaml +++ b/data/api/client-server/room_upgrades.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/rooms.yaml b/data/api/client-server/rooms.yaml index 2f161e2b..64079b89 100644 --- a/data/api/client-server/rooms.yaml +++ b/data/api/client-server/rooms.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/search.yaml b/data/api/client-server/search.yaml index 8bc25528..b1f6359d 100644 --- a/data/api/client-server/search.yaml +++ b/data/api/client-server/search.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/sso_login_redirect.yaml b/data/api/client-server/sso_login_redirect.yaml index b58d88fe..eb51f7c8 100644 --- a/data/api/client-server/sso_login_redirect.yaml +++ b/data/api/client-server/sso_login_redirect.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 paths: "/login/sso/redirect": get: diff --git a/data/api/client-server/sync.yaml b/data/api/client-server/sync.yaml index 6d711c51..ca788429 100644 --- a/data/api/client-server/sync.yaml +++ b/data/api/client-server/sync.yaml @@ -18,7 +18,7 @@ info: host: localhost:8008 schemes: - https -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/tags.yaml b/data/api/client-server/tags.yaml index 94e7be07..f04a884a 100644 --- a/data/api/client-server/tags.yaml +++ b/data/api/client-server/tags.yaml @@ -20,7 +20,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/third_party_lookup.yaml b/data/api/client-server/third_party_lookup.yaml index 6f882965..f56554e3 100644 --- a/data/api/client-server/third_party_lookup.yaml +++ b/data/api/client-server/third_party_lookup.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: @@ -196,7 +196,7 @@ paths: security: - accessToken: [] parameters: - - in: query + - in: query name: userid type: string description: The Matrix User ID to look up. diff --git a/data/api/client-server/third_party_membership.yaml b/data/api/client-server/third_party_membership.yaml index c48b4697..cf4a0d34 100644 --- a/data/api/client-server/third_party_membership.yaml +++ b/data/api/client-server/third_party_membership.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: @@ -36,7 +36,7 @@ paths: identifier of the invitee, and instead relies on third party identifiers. The homeserver uses an identity server to perform the mapping from third party identifier to a Matrix identifier. The other is documented in the* - [joining rooms section](/client-server-api/#post_matrixclientr0roomsroomidinvite). + [joining rooms section](/client-server-api/#post_matrixclientv3roomsroomidinvite). This API invites a user to participate in a particular room. They do not start participating in the room until they actually join the diff --git a/data/api/client-server/to_device.yaml b/data/api/client-server/to_device.yaml index a4d2f6dd..c74aee55 100644 --- a/data/api/client-server/to_device.yaml +++ b/data/api/client-server/to_device.yaml @@ -20,7 +20,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/typing.yaml b/data/api/client-server/typing.yaml index c7138950..65a1225d 100644 --- a/data/api/client-server/typing.yaml +++ b/data/api/client-server/typing.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/users.yaml b/data/api/client-server/users.yaml index ae015e7a..7a6f6856 100644 --- a/data/api/client-server/users.yaml +++ b/data/api/client-server/users.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/voip.yaml b/data/api/client-server/voip.yaml index 75ace4c3..6c0d1816 100644 --- a/data/api/client-server/voip.yaml +++ b/data/api/client-server/voip.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 consumes: - application/json produces: diff --git a/data/api/client-server/whoami.yaml b/data/api/client-server/whoami.yaml index 54d9cde9..b17c092f 100644 --- a/data/api/client-server/whoami.yaml +++ b/data/api/client-server/whoami.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/client/v3 produces: - application/json securityDefinitions: diff --git a/layouts/shortcodes/http-api.html b/layouts/shortcodes/http-api.html index b4bc6d0d..32e0ad41 100644 --- a/layouts/shortcodes/http-api.html +++ b/layouts/shortcodes/http-api.html @@ -20,7 +20,7 @@ {{ $api := .Params.api}} {{ $api_data := index .Site.Data.api .Params.spec .Params.api }} -{{ $base_url := replace $api_data.basePath "%CLIENT_MAJOR_VERSION%" "r0" }} +{{ $base_url := $api_data.basePath }} {{ $path := delimit (slice "api" $spec) "/" }} {{ partial "openapi/render-api" (dict "api_data" $api_data "base_url" $base_url "path" $path) }} diff --git a/openapi_extensions.md b/openapi_extensions.md index b450e49f..6f3e92a8 100644 --- a/openapi_extensions.md +++ b/openapi_extensions.md @@ -9,15 +9,13 @@ parsers should be able to take advantage of the added syntax. ## Using multiple files to describe API To ease API design and management, the API definition is split across several -files. Each of these files is self-contained valid OpenAPI (except -client-server files that become valid OpenAPI after substituting -`%CLIENT_MAJOR_VERSION%` with `unstable` or an API release). +files. Each of these files is self-contained valid OpenAPI. There is no single root file in the source tree as OpenAPI requires; this file can be generated by `dump_swagger.py` (also doing the substitution mentioned above). The script does not convert the extensions described further in this document (`oneOf` and parameter exploding) so there can be minor -interoperability issues with tooling that expects compliant Swagger. +interoperability issues with tooling that expects compliant Swagger. ## Extensible Query Parameters diff --git a/scripts/dump-swagger.py b/scripts/dump-swagger.py index bfe392c9..9e6ce156 100755 --- a/scripts/dump-swagger.py +++ b/scripts/dump-swagger.py @@ -107,8 +107,6 @@ for filename in os.listdir(cs_api_dir): basePath = api['basePath'] for path, methods in api["paths"].items(): - path = (basePath + path).replace('%CLIENT_MAJOR_VERSION%', - major_version) for method, spec in methods.items(): if "tags" in spec.keys(): if path not in output["paths"]: @@ -126,5 +124,4 @@ except OSError as e: with open(output_file, "w") as f: text = json.dumps(output, sort_keys=True, indent=4) text = text.replace("%CLIENT_RELEASE_LABEL%", release_label) - text = text.replace("%CLIENT_MAJOR_VERSION%", major_version) f.write(text)