note that version is optional for GET, and say what to do when no keys are found
@@ -238,6 +238,9 @@ Returns the same as `PUT
#### Retrieving keys
+When retrieving keys, the `version` parameter is optional, and defaults to
+retrieving the latest backup version.
+
##### `GET /room_keys/keys/${roomId}/${sessionId}?version=$v`
Retrieve the key for the given session in the given room from the backup.
@@ -245,6 +248,10 @@ Retrieve the key for the given session in the given room from the backup.
On success, returns a JSON object in the same form as the request body of `PUT
/room_keys/keys/${roomId}/${sessionId}?version=$v`.
+Error codes:
+
+- M_NOT_FOUND: The session is not present in the backup.
+
##### `GET /room_keys/keys/${roomId}?version=$v`
Retrieve the all the keys for the given room from the backup.
@@ -252,6 +259,15 @@ Retrieve the all the keys for the given room from the backup.
On success, returns a JSON object in the same form as the request body of `PUT
/room_keys/keys/${roomId}?version=$v`.
+If no keys are found, then this endpoint returns a successful response with
+body:
+
+```
+{
+ "sessions": {}
+}
+```
+
##### `GET /room_keys/keys?version=$v`
Retrieve all the keys from the backup.
@@ -259,6 +275,16 @@ Retrieve all the keys from the backup.
On success, returns a JSON object in the same form as the request body of `PUT
/room_keys/keys?version=$v`.
+
+If no keys are found, then this endpoint returns a successful response with
+body:
+
+```
+{
+ "rooms": {}
+}
+```
+
#### Deleting keys
##### `DELETE /room_keys/keys/${roomId}/${sessionId}?version=$v`
