Specify the order in which one-time keys are returned (MSC4225) (#2029)

Signed-off-by: Andy Balaam <andy.balaam@matrix.org>

changelogs/client_server/newsfragments/2029.clarification

@@ -0,0 +1 @@
+Specify order that one-time keys are issued by `/keys/claim`, as per [MSC4225](https://github.com/matrix-org/matrix-spec-proposals/pull/4225).

data/api/client-server/keys.yaml

@@ -288,7 +288,22 @@ paths:
   /keys/claim:
     post:
       summary: Claim one-time encryption keys.
-      description: Claims one-time keys for use in pre-key messages.
+      description: |-
+        Claims one-time keys for use in pre-key messages.
+
+        The request contains the user ID, device ID and algorithm name of the
+        keys that are required. If a key matching these requirements can be
+        found, the response contains it. The returned key is a one-time key
+        if one is available, and otherwise a fallback key.
+
+        One-time keys are given out in the order that they were uploaded via
+        [/keys/upload](/client-server-api/#post_matrixclientv3keysupload). (All
+        keys uploaded within a given call to `/keys/upload` are considered
+        equivalent in this regard; no ordering is specified within them.)
+
+        Servers must ensure that each one-time key is returned at most once,
+        so when a key has been returned, no other request will ever return
+        the same key.
       operationId: claimKeys
       security:
         - accessTokenQuery: []

data/api/server-server/user_keys.yaml

@@ -20,7 +20,22 @@ paths:
   /user/keys/claim:
     post:
       summary: Claims one-time encryption keys for a user.
-      description: Claims one-time keys for use in pre-key messages.
+      description: |-
+        Claims one-time keys for use in pre-key messages.
+
+        The request contains the user ID, device ID and algorithm name of the
+        keys that are required. If a key matching these requirements can be
+        found, the response contains it. The returned key is a one-time key
+        if one is available, and otherwise a fallback key.
+
+        One-time keys are given out in the order that they were uploaded via
+        [/keys/upload](/client-server-api/#post_matrixclientv3keysupload). (All
+        keys uploaded within a given call to `/keys/upload` are considered
+        equivalent in this regard; no ordering is specified within them.)
+
+        Servers must ensure that each one-time key is returned at most once,
+        so when a key has been returned, no other request will ever return
+        the same key.
       operationId: claimUserEncryptionKeys
       security:
         - signedRequest: []