diff --git a/proposals/2666-get-rooms-in-common.md b/proposals/2666-get-rooms-in-common.md index 08ce12aa..f63371d5 100644 --- a/proposals/2666-get-rooms-in-common.md +++ b/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": "" + "next_batch": "" } ``` -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