apply review feedback (#4035)

Author: ShadowJonathan

proposals/2666-get-rooms-in-common.md

@@ -26,14 +26,19 @@ Homeservers will implement a new endpoint `/_matrix/client/v1/user/mutual_rooms`
 This endpoint will take a query parameter of `user_id` which will contain the MXID of the user
 matched against.
 
-This endpoint can be rate limited.
+This endpoint can be rate limited and requires authentication.
 
 The response format will be an array containing all rooms where both the authenticated user and
-`user_id` have a membership of type `join`. If the `user_id` does not exist, or does not share any
-rooms with the authenticated user, an empty array should be returned.
+`user_id` have a membership of type `join`.
+
+If the `user_id` does not exist, or does not share any rooms with the authenticated user,
+an empty array should be returned.
+
+Handling invalid user IDs should result in an error, is likely implementation-specific,
+and is beyond the scope of this proposal.
 
 ```http
-GET /_matrix/client/v1/user/mutual_rooms/?user_id=%40bob%3Aexample.com
+GET /_matrix/client/v1/user/mutual_rooms?user_id=%40bob%3Aexample.com
 ```
 
 ```json
@@ -47,24 +52,29 @@ GET /_matrix/client/v1/user/mutual_rooms/?user_id=%40bob%3Aexample.com
 ```
 
 The server may decide that the response to this endpoint is too large, and thus an optional key
-`"next_batch_token"` can be inserted, which the client has to pass to `batch_token` in the query
+`"next_batch"` can be inserted, which the client has to pass to `from` in the query
 parameters together with the original `user_id` to fetch the next batch of responses. This will
-continue until the server does no longer insert `"next_batch_token"`.
+continue until the server does no longer insert `"next_batch"`.
 
 ```json5
 {
   "joined": [
     // ...
   ],
-  "next_batch_token": "<a string up to 32 characters abiding by the regex /[a-zA-Z0-9]+/>"
+  "next_batch": "<an opaque identifier, containing only the characters [0-9a-zA-Z._~-], non-empty if not omitted, and at most 255 characters>"
 }
 ```
 
-The response error for when the given `batch_token` is invalid will be a response with HTTP code 400,
+The batch tokens this endpoint generates are only valid for this endpoint.
+
+The response error for when the given `from` batch token is invalid will be a response with HTTP code 400,
 with `M_INVALID_PARAM` as `errcode`.
 
-The response error for trying to get shared rooms with yourself will be an HTTP code 422, with
-`M_INVALID_PARAM` as the `errcode`.
+The response error for trying to get shared rooms with yourself will be an HTTP code 400, with
+`M_UNKNOWN` as the `errcode`. And the error description may be "you cannot request rooms in common with yourself".
+
+Tokens generated by this endpoint must be valid for at least 10 minutes, after which, tokens can expire.
+Expired tokens must be handled similar to invalid tokens, as described above.
 
 ## Potential issues