From 1bc0f63bfb26f7f60f034c6bdcf38b901005516b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 Aug 2018 21:03:48 -0600 Subject: [PATCH 1/4] Clarify the homeserver's behaviour for user searching The homeserver can implement its own algorithm, but is suggested to ensure the requesting user can reasonably see the other users. The text is intentionally left vague for whether or not the API is local users only to give the homeserver some flexibility in this area. General cleanup is also included in this commit. Fixes https://github.com/matrix-org/matrix-doc/issues/1108 --- api/client-server/users.yaml | 29 +++++++++++++++++------------ 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/api/client-server/users.yaml b/api/client-server/users.yaml index a682b435..ef527a23 100644 --- a/api/client-server/users.yaml +++ b/api/client-server/users.yaml @@ -31,8 +31,13 @@ paths: post: summary: Searches the user directory. description: |- - This API performs a server-side search over all users registered on the server. - It searches user ID and displayname case-insensitively for users that you share a room with or that are in public rooms. + Performs a search for users on the homeserver. The homeserver may + determine which subset of users are searched, however the homeserver + is encouraged to only consider users the requesting user shares a + room with and those who reside in public rooms. + + The search is performed case-insensitively on user IDs and display + names. operationId: searchUserDirectory security: - accessToken: [] @@ -48,7 +53,7 @@ paths: example: "foo" limit: type: number - description: The maximum number of results to return (Defaults to 10). + description: The maximum number of results to return. Defaults to 10. example: 10 required: ["search_term"] responses: @@ -56,15 +61,15 @@ paths: description: The results of the search. examples: application/json: { - "results": [ - { - "user_id": "@foo:bar.com", - "display_name": "Foo", - "avatar_url": "mxc://bar.com/foo" - } - ], - "limited": false - } + "results": [ + { + "user_id": "@foo:bar.com", + "display_name": "Foo", + "avatar_url": "mxc://bar.com/foo" + } + ], + "limited": false + } schema: type: object required: ["results", "limited"] From e926b4a84011332a698189ec421993d4d5605388 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 Aug 2018 21:05:09 -0600 Subject: [PATCH 2/4] Changelog --- changelogs/client_server/newsfragments/1569.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1569.clarification diff --git a/changelogs/client_server/newsfragments/1569.clarification b/changelogs/client_server/newsfragments/1569.clarification new file mode 100644 index 00000000..83185e02 --- /dev/null +++ b/changelogs/client_server/newsfragments/1569.clarification @@ -0,0 +1 @@ +Clarify the homeserver's behaviour for searching users. From bb515d15a40470fc2c9a9290428b8fcf675ec0c1 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Aug 2018 18:55:54 -0600 Subject: [PATCH 3/4] Clarify which collation to use for user directory searching --- api/client-server/users.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/api/client-server/users.yaml b/api/client-server/users.yaml index ef527a23..619263ff 100644 --- a/api/client-server/users.yaml +++ b/api/client-server/users.yaml @@ -37,7 +37,8 @@ paths: room with and those who reside in public rooms. The search is performed case-insensitively on user IDs and display - names. + names preferably using a collation determined based upon the + ``Accept-Language`` header provided in the request, if present. operationId: searchUserDirectory security: - accessToken: [] From f2332d242aeb079e77396bd6bd8c5d7f2a629b7e Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Aug 2018 18:58:16 -0600 Subject: [PATCH 4/4] Add some SHOULDs and MUSTs to the user directory requirements --- api/client-server/users.yaml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/api/client-server/users.yaml b/api/client-server/users.yaml index 619263ff..8a60a7bc 100644 --- a/api/client-server/users.yaml +++ b/api/client-server/users.yaml @@ -33,8 +33,10 @@ paths: description: |- Performs a search for users on the homeserver. The homeserver may determine which subset of users are searched, however the homeserver - is encouraged to only consider users the requesting user shares a - room with and those who reside in public rooms. + MUST at a minimum consider the users the requesting user shares a + room with and those who reside in public rooms (known to the homeserver). + The search MUST consider local users to the homeserver, and SHOULD + query remote users as part of the search. The search is performed case-insensitively on user IDs and display names preferably using a collation determined based upon the