client-api: Refactor backup APIs to be more descriptive and accurate

crates/ruma-client-api/src/backup.rs

@@ -1,19 +1,19 @@
 //! Endpoints for server-side key backups.
 
-pub mod add_backup_key_session;
-pub mod add_backup_key_sessions;
 pub mod add_backup_keys;
-pub mod create_backup;
+pub mod add_backup_keys_for_room;
-pub mod delete_backup;
+pub mod add_backup_keys_for_session;
-pub mod delete_backup_key_session;
+pub mod create_backup_version;
-pub mod delete_backup_key_sessions;
 pub mod delete_backup_keys;
-pub mod get_backup;
+pub mod delete_backup_keys_for_room;
-pub mod get_backup_key_session;
+pub mod delete_backup_keys_for_session;
-pub mod get_backup_key_sessions;
+pub mod delete_backup_version;
+pub mod get_backup_info;
 pub mod get_backup_keys;
-pub mod get_latest_backup;
+pub mod get_backup_keys_for_room;
-pub mod update_backup;
+pub mod get_backup_keys_for_session;
+pub mod get_latest_backup_info;
+pub mod update_backup_version;
 
 use std::collections::BTreeMap;
 

crates/ruma-client-api/src/backup/add_backup_keys.rs

@@ -15,7 +15,7 @@ pub mod v3 {
 
     ruma_api! {
         metadata: {
-            description: "Store several keys in the backup.",
+            description: "Store keys in the backup.",
             method: PUT,
             name: "add_backup_keys",
             unstable_path: "/_matrix/client/unstable/room_keys/keys",
@@ -26,13 +26,13 @@ pub mod v3 {
         }
 
         request: {
-            /// The backup version.
+            /// The backup version to add keys to.
             ///
             /// Must be the current backup.
             #[ruma_api(query)]
             pub version: &'a str,
 
-            /// A map from room IDs to session IDs to key data.
+            /// A map of room IDs to session IDs to key data to store.
             pub rooms: BTreeMap<Box<RoomId>, RoomKeyBackup>,
         }
 

crates/ruma-client-api/src/backup/add_backup_keys_for_room.rs

@@ -16,9 +16,9 @@ pub mod v3 {
 
     ruma_api! {
         metadata: {
-            description: "Store several sessions in the backup.",
+            description: "Store keys in the backup for a room.",
             method: PUT,
-            name: "add_backup_key_sessions",
+            name: "add_backup_keys_for_room",
             unstable_path: "/_matrix/client/unstable/room_keys/keys/:room_id",
             r0_path: "/_matrix/client/r0/room_keys/keys/:room_id",
             stable_path: "/_matrix/client/v3/room_keys/keys/:room_id",
@@ -28,17 +28,17 @@ pub mod v3 {
         }
 
         request: {
-            /// The backup version.
+            /// The backup version to add keys to.
             ///
             /// Must be the current backup.
             #[ruma_api(query)]
             pub version: &'a str,
 
-            /// The ID of the room that the requested key is for.
+            /// The ID of the room to add keys to.
             #[ruma_api(path)]
             pub room_id: &'a RoomId,
 
-            /// A map from session IDs to key data.
+            /// A map of session IDs to key data to store.
             pub sessions: BTreeMap<String, Raw<KeyBackupData>>,
         }
 

crates/ruma-client-api/src/backup/add_backup_keys_for_session.rs

@@ -14,9 +14,9 @@ pub mod v3 {
 
     ruma_api! {
         metadata: {
-            description: "Store several keys in the backup.",
+            description: "Store keys in the backup for a session.",
             method: PUT,
-            name: "add_backup_key_session",
+            name: "add_backup_keys_for_session",
             unstable_path: "/_matrix/client/unstable/room_keys/keys/:room_id/:session_id",
             r0_path: "/_matrix/client/r0/room_keys/keys/:room_id/:session_id",
             stable_path: "/_matrix/client/v3/room_keys/keys/:room_id/:session_id",
@@ -26,21 +26,21 @@ pub mod v3 {
         }
 
         request: {
-            /// The backup version.
+            /// The backup version to add keys to.
             ///
             /// Must be the current backup.
             #[ruma_api(query)]
             pub version: &'a str,
 
-            /// The ID of the room that the requested key is for.
+            /// The ID of the room to add keys to.
             #[ruma_api(path)]
             pub room_id: &'a RoomId,
 
-            /// The ID of the megolm session whose key is requested.
+            /// The ID of the megolm session to add keys to.
             #[ruma_api(path)]
             pub session_id: &'a str,
 
-            /// The key information to backup.
+            /// The key information to store.
             #[ruma_api(body)]
             pub session_data: Raw<KeyBackupData>,
         }

crates/ruma-client-api/src/backup/create_backup_version.rs

@@ -12,9 +12,9 @@ pub mod v3 {
 
     ruma_api! {
         metadata: {
-            description: "Creates a new backup.",
+            description: "Create a new backup version.",
             method: POST,
-            name: "create_backup",
+            name: "create_backup_version",
             unstable_path: "/_matrix/client/unstable/room_keys/version",
             stable_path: "/_matrix/client/v3/room_keys/version",
             rate_limited: true,

crates/ruma-client-api/src/backup/delete_backup_keys.rs

@@ -4,13 +4,15 @@ pub mod v3 {
     //! `/v3/` ([spec])
     //!
     //! [spec]: https://spec.matrix.org/v1.2/client-server-api/#delete_matrixclientv3room_keyskeys
+    //!
+    //! This deletes keys from a backup version, but not the version itself.
 
     use js_int::UInt;
     use ruma_api::ruma_api;
 
     ruma_api! {
         metadata: {
-            description: "Delete all keys in a backup.",
+            description: "Delete all keys from a backup.",
             method: DELETE,
             name: "delete_backup_keys",
             unstable_path: "/_matrix/client/unstable/room_keys/keys",
@@ -22,9 +24,7 @@ pub mod v3 {
         }
 
         request: {
-            /// The backup version.
+            /// The backup version from which to delete keys.
-            ///
-            /// Must be the current backup.
             #[ruma_api(query)]
             pub version: &'a str,
         }

crates/ruma-client-api/src/backup/delete_backup_keys_for_room.rs

@@ -11,9 +11,9 @@ pub mod v3 {
 
     ruma_api! {
         metadata: {
-            description: "Delete keys from the backup for a given room.",
+            description: "Delete keys from a backup for a given room.",
             method: DELETE,
-            name: "delete_backup_key_sessions",
+            name: "delete_backup_keys_for_room",
             unstable_path: "/_matrix/client/unstable/room_keys/keys/:room_id",
             r0_path: "/_matrix/client/r0/room_keys/keys/:room_id",
             stable_path: "/_matrix/client/v3/room_keys/keys/:room_id",
@@ -23,13 +23,11 @@ pub mod v3 {
         }
 
         request: {
-            /// The backup version.
+            /// The backup version from which to delete keys.
-            ///
-            /// Must be the current backup.
             #[ruma_api(query)]
             pub version: &'a str,
 
-            /// The ID of the room that the requested key is for.
+            /// The ID of the room to delete keys from.
             #[ruma_api(path)]
             pub room_id: &'a RoomId,
         }

crates/ruma-client-api/src/backup/delete_backup_keys_for_session.rs

@@ -11,9 +11,9 @@ pub mod v3 {
 
     ruma_api! {
         metadata: {
-            description: "Delete a key from the backup",
+            description: "Delete keys from a backup for a given session.",
             method: DELETE,
-            name: "delete_backup_key_session",
+            name: "delete_backup_keys_for_session",
             unstable_path: "/_matrix/client/unstable/room_keys/keys/:room_id/:session_id",
             r0_path: "/_matrix/client/r0/room_keys/keys/:room_id/:session_id",
             stable_path: "/_matrix/client/v3/room_keys/keys/:room_id/:session_id",
@@ -23,17 +23,15 @@ pub mod v3 {
         }
 
         request: {
-            /// The backup version.
+            /// The backup version from which to delete keys.
-            ///
-            /// Must be the current backup.
             #[ruma_api(query)]
             pub version: &'a str,
 
-            /// The ID of the room that the requested key is for.
+            /// The ID of the room to delete keys from.
             #[ruma_api(path)]
             pub room_id: &'a RoomId,
 
-            /// The ID of the megolm session whose key is requested.
+            /// The ID of the megolm session to delete keys from.
             #[ruma_api(path)]
             pub session_id: &'a str,
         }

crates/ruma-client-api/src/backup/delete_backup_version.rs

@@ -4,14 +4,16 @@ pub mod v3 {
     //! `/v3/` ([spec])
     //!
     //! [spec]: https://spec.matrix.org/v1.2/client-server-api/#delete_matrixclientv3room_keysversionversion
+    //!
+    //! This deletes a backup version and its room keys.
 
     use ruma_api::ruma_api;
 
     ruma_api! {
         metadata: {
-            description: "Delete an existing backup.",
+            description: "Delete a backup version.",
             method: DELETE,
-            name: "delete_backup",
+            name: "delete_backup_version",
             unstable_path: "/_matrix/client/unstable/room_keys/version/:version",
             r0_path: "/_matrix/client/r0/room_keys/version/:version",
             stable_path: "/_matrix/client/v3/room_keys/version/:version",
@@ -21,7 +23,7 @@ pub mod v3 {
         }
 
         request: {
-            /// The backup version.
+            /// The backup version to delete.
             #[ruma_api(path)]
             pub version: &'a str,
         }

crates/ruma-client-api/src/backup/get_backup_info.rs

@@ -1,4 +1,6 @@
 //! `GET /_matrix/client/*/room_keys/version/{version}`
+//!
+//! Get information about a specific backup.
 
 pub mod v3 {
     //! `/v3/` ([spec])
@@ -15,9 +17,9 @@ pub mod v3 {
 
     ruma_api! {
         metadata: {
-            description: "Get information about an existing backup.",
+            description: "Get information about a specific backup.",
             method: GET,
-            name: "get_backup",
+            name: "get_backup_info",
             unstable_path: "/_matrix/client/unstable/room_keys/version/:version",
             stable_path: "/_matrix/client/v3/room_keys/version/:version",
             rate_limited: true,
@@ -26,7 +28,7 @@ pub mod v3 {
         }
 
         request: {
-            /// The backup version.
+            /// The backup version to retrieve info from.
             #[ruma_api(path)]
             pub version: &'a str,
         }

crates/ruma-client-api/src/backup/get_backup_keys.rs

@@ -1,4 +1,6 @@
 //! `GET /_matrix/client/*/room_keys/keys`
+//!
+//! Retrieve all keys from a backup version.
 
 pub mod v3 {
     //! `/v3/` ([spec])
@@ -14,7 +16,7 @@ pub mod v3 {
 
     ruma_api! {
         metadata: {
-            description: "Retrieve all keys from a backup.",
+            description: "Retrieve all keys from a backup version.",
             method: GET,
             name: "get_backup_keys",
             unstable_path: "/_matrix/client/unstable/room_keys/keys",
@@ -26,9 +28,7 @@ pub mod v3 {
         }
 
         request: {
-            /// The backup version.
+            /// The backup version to retrieve keys from.
-            ///
-            /// Must be the current backup.
             #[ruma_api(query)]
             pub version: &'a str,
         }

crates/ruma-client-api/src/backup/get_backup_keys_for_room.rs

@@ -17,7 +17,7 @@ pub mod v3 {
         metadata: {
             description: "Retrieve sessions from the backup for a given room.",
             method: GET,
-            name: "get_backup_key_sessions",
+            name: "get_backup_keys_for_room",
             unstable_path: "/_matrix/client/unstable/room_keys/keys/:room_id",
             r0_path: "/_matrix/client/r0/room_keys/keys/:room_id",
             stable_path: "/_matrix/client/v3/room_keys/keys/:room_id",
@@ -27,9 +27,7 @@ pub mod v3 {
         }
 
         request: {
-            /// The backup version
+            /// The backup version to retrieve keys from.
-            ///
-            /// Must be the current backup.
             #[ruma_api(query)]
             pub version: &'a str,
 

crates/ruma-client-api/src/backup/get_backup_keys_for_session.rs

@@ -13,9 +13,9 @@ pub mod v3 {
 
     ruma_api! {
         metadata: {
-            description: "Retrieve a key from the backup",
+            description: "Retrieve a key from the backup for a given session.",
             method: GET,
-            name: "get_backup_key_session",
+            name: "get_backup_keys_for_session",
             unstable_path: "/_matrix/client/unstable/room_keys/keys/:room_id/:session_id",
             r0_path: "/_matrix/client/r0/room_keys/keys/:room_id/:session_id",
             stable_path: "/_matrix/client/v3/room_keys/keys/:room_id/:session_id",
@@ -25,9 +25,7 @@ pub mod v3 {
         }
 
         request: {
-            /// The backup version.
+            /// The backup version to retrieve keys from.
-            ///
-            /// Must be the current backup.
             #[ruma_api(query)]
             pub version: &'a str,
 

crates/ruma-client-api/src/backup/get_latest_backup_info.rs

@@ -12,7 +12,7 @@ pub mod v3 {
     use serde_json::value::to_raw_value as to_raw_json_value;
 
     use crate::backup::{
-        get_backup::v3::{AlgorithmWithData, RefResponseBodyRepr, ResponseBodyRepr},
+        get_backup_info::v3::{AlgorithmWithData, RefResponseBodyRepr, ResponseBodyRepr},
         BackupAlgorithm,
     };
 
@@ -20,7 +20,7 @@ pub mod v3 {
         metadata: {
             description: "Get information about the latest backup.",
             method: GET,
-            name: "get_latest_backup",
+            name: "get_latest_backup_info",
             unstable_path: "/_matrix/client/unstable/room_keys/version",
             r0_path: "/_matrix/client/r0/room_keys/version",
             stable_path: "/_matrix/client/v3/room_keys/version",

crates/ruma-client-api/src/backup/update_backup_version.rs

@@ -14,12 +14,12 @@ pub mod v3 {
         metadata: {
             description: "Update information about an existing backup.",
             method: PUT,
-            name: "update_backup",
+            name: "update_backup_version",
             unstable_path: "/_matrix/client/unstable/room_keys/version/:version",
             stable_path: "/_matrix/client/v3/room_keys/version/:version",
             rate_limited: true,
             authentication: AccessToken,
-            added: 1.1,
+            added: 1.0,
         }
 
         request: {