From 1bc0f63bfb26f7f60f034c6bdcf38b901005516b Mon Sep 17 00:00:00 2001
From: Travis Ralston <travpc@gmail.com>
Date: Sun, 26 Aug 2018 21:03:48 -0600
Subject: [PATCH] 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"]