From 0145191d43d4c9021bc43ad3bb36caae468d6537 Mon Sep 17 00:00:00 2001
From: Hubert Chathi <hubert@uhoreg.ca>
Date: Tue, 5 May 2020 20:00:45 -0400
Subject: [PATCH] add links to endpoints and add delete endpoint

---
 api/client-server/key_backup.yaml             | 37 +++++++++++++++++++
 .../modules/end_to_end_encryption.rst         | 21 ++++++-----
 2 files changed, 49 insertions(+), 9 deletions(-)

diff --git a/api/client-server/key_backup.yaml b/api/client-server/key_backup.yaml
index ae729d62..387621e6 100644
--- a/api/client-server/key_backup.yaml
+++ b/api/client-server/key_backup.yaml
@@ -230,6 +230,43 @@ paths:
             "$ref": "definitions/errors/error.yaml"
       tags:
         - End-to-end encryption
+    delete:
+      summary: Delete an existing key backup.
+      description: |-
+        Delete an existing key backup. Both the information about the backup,
+        as well as all key data related to the backup will be deleted.
+      operationId: deleteRoomKeysVersion
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: version
+          description: |-
+            The backup version to delete, as returned in the ``version``
+            parameter in the response of `POST
+            /_matrix/client/r0/room_keys/version`_ or `GET
+            /_matrix/client/r0/room_keys/version/{version}`_. Unlike with the
+            ``GET`` version of this endpoint, this may not be empty.
+          required: true
+          x-example: "1"
+      responses:
+        200:
+          description: The delete succeeded.
+          schema:
+            type: object
+            properties: {}
+        404:
+          description: The backup specified does not exist.
+          examples:
+            application/json: {
+                "errcode": "M_NOT_FOUND",
+                "error": "Unknown backup version"
+              }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+      tags:
+        - End-to-end encryption
   "/room_keys/keys/{roomId}/{sessionId}":
     put:
       summary: Store a key in the backup.
diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst
index 48a2d6ca..d6c87bc3 100644
--- a/specification/modules/end_to_end_encryption.rst
+++ b/specification/modules/end_to_end_encryption.rst
@@ -780,15 +780,18 @@ device to be online from which to request keys. 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 /room_keys/version`` and define
-how the keys are to be encrypted through the backup's ``auth_data``; other
-clients can discover the backup by calling ``GET /room_keys/version``.  Keys
-are encrypted according to the backups ``auth_data`` and added to the backup by
-calling ``PUT /room_keys/keys?version=$v`` or one of its variants, and can be
-retrieved by calling ``GET /room_keys/keys?version=$v`` 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 /room_keys/version``, or individual
-keys can be deleted using ``DELETE /room_key/keys?version=$v`` or one of its
+To create a backup, a client will call `POST
+/_matrix/client/r0/room_keys/version`_ 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/{version}`_,
+setting ``{version}`` to the empty string.  Keys are encrypted according to the
+backups ``auth_data`` and added to the backup by calling `PUT
+/_matrix/client/r0/room_keys/keys`_ or one of its variants, and can be
+retrieved by calling `GET /_matrix/client/r0/room_keys/keys`_ 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}`_, or individual keys can be
+deleted using `DELETE /_matrix/client/r0/room_keys/keys`_ or one of its
 variants.
 
 Clients must only store keys in backups after they have ensured that the