add user_directory #1096

t3chguy · 2017-12-17T23:43:53Z

No description provided.

turt2live · 2017-12-18T00:11:45Z

operationId is missing in /user_directory/search, verb post

richvdh · 2017-12-18T10:22:22Z

I think this fixes #953

richvdh · 2017-12-18T10:21:07Z

api/client-server/users.yaml

@@ -0,0 +1,93 @@
+# Copyright 2016 OpenMarket Ltd


it's not 2016, and you don't work for openmarket. (you may be after New Vector Ltd or Michael Telatynski, depending which hat you feel like wearing)

the woes of Copying entire files and my IDE collapsing the header and never actually seeing this

richvdh · 2017-12-18T10:21:15Z

api/client-server/users.yaml

+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Profile API"


not the profile api

richvdh · 2017-12-18T13:06:25Z

changelogs/client_server.rst

@@ -76,6 +76,9 @@ r0.3.0
    - ``GET /media/{version}/preview_url``
      (`#1064 <https://github.com/matrix-org/matrix-doc/pull/1064>`_).

+    - ``POST /user_directory/search``


Needs to go under 'unreleased changes', please.

richvdh · 2017-12-18T13:07:14Z

api/client-server/users.yaml

+  $ref: definitions/security.yaml
+paths:
+  "/user_directory/search":
+    post:


as Travis says, this is missing its operationId.

richvdh · 2017-12-18T13:10:10Z

api/client-server/users.yaml

+            required: ["search_term"]
+      responses:
+        200:
+          description: The results of the paginated search.


erm, "the paginated results of the search", surely. Or probably just "The results of the search".

richvdh · 2017-12-18T13:11:47Z

api/client-server/users.yaml

+                example: "foo"
+              limit:
+                type: number
+                description: The maximum number of results to return


if this is optional, what's the behaviour when it's omitted?

richvdh · 2017-12-18T13:11:52Z

api/client-server/users.yaml

+    post:
+      summary: Searches the user directory.
+      description: |-
+        This API paginates over search results of the user directory.


I think this emphasises the pagination too strongly. Not least because aiui pagination isn't currently supported. How about "Performs a server-side search over all users registered on the server".

could you also give some details about how the search works. Is it case-sensitive? Does it search displayname, mxid, both?

richvdh · 2017-12-18T13:12:49Z

api/client-server/users.yaml

+                items:
+                  title: User
+                  type: object
+                  properties:


is user_id not required here?

richvdh · 2017-12-18T13:14:17Z

api/client-server/users.yaml

+            type: object
+            required: ["results", "limited"]
+            properties:
+              results:


do we know anything about the ordering of the results?

vaguely, seems implementation specific

richvdh · 2017-12-18T13:20:17Z

specification/client_server_api.rst

@@ -1335,6 +1335,13 @@ Listing rooms

 {{list_public_rooms_cs_http_api}}

+
+Users


I think it might be worth merging this and profiles into a generic user data section.

t3chguy · 2017-12-18T17:08:00Z

back to you @richvdh

richvdh · 2017-12-20T10:13:12Z

api/client-server/users.yaml

-        This API paginates over search results of the user directory.
+        This API performs a server-side search over all users registered on the server.
+        Searches MXID and displayname case-insesitively for users that you share a room with or that are in public rooms.
+      operationId: postUserDirectorySearch


why postUserDirectorySearch? seems inconsistent with everything else.

richvdh · 2017-12-20T10:15:10Z

api/client-server/users.yaml

@@ -31,7 +31,9 @@ paths:
    post:
      summary: Searches the user directory.
      description: |-
-        This API paginates over search results of the user directory.
+        This API performs a server-side search over all users registered on the server.
+        Searches MXID and displayname case-insesitively for users that you share a room with or that are in public rooms.


insesitively

richvdh · 2017-12-20T10:15:35Z

api/client-server/users.yaml

@@ -31,7 +31,9 @@ paths:
    post:
      summary: Searches the user directory.
      description: |-
-        This API paginates over search results of the user directory.
+        This API performs a server-side search over all users registered on the server.
+        Searches MXID and displayname case-insesitively for users that you share a room with or that are in public rooms.


full sentence here please.

richvdh · 2017-12-20T10:20:47Z

api/client-server/users.yaml

@@ -46,12 +48,12 @@ paths:
                example: "foo"
              limit:
                type: number
-                description: The maximum number of results to return
+                description: The maximum number of results to return (10 if omitted), with a maximum of 50


I'm not sure that the maximum here needs speccing, and if it does, it probably belongs in a note in the api description rather than that of the summary.

richvdh · 2017-12-20T10:21:46Z

api/client-server/users.yaml

@@ -46,12 +48,12 @@ paths:
                example: "foo"
              limit:
                type: number
-                description: The maximum number of results to return
+                description: The maximum number of results to return (10 if omitted), with a maximum of 50


suggest you use 'Defaults to 10' instead of (10 if omitted).

rav@fred:~/work/matrix-doc (master $%=)$ grep -ir 'if omitted' api/client-server/ | wc -l 1 rav@fred:~/work/matrix-doc (master $%=)$ grep -ir 'Defaults to' api/client-server/ | wc -l 6

richvdh · 2017-12-20T10:22:25Z

api/client-server/users.yaml

@@ -46,12 +48,12 @@ paths:
                example: "foo"
              limit:
                type: number
-                description: The maximum number of results to return
+                description: The maximum number of results to return (10 if omitted), with a maximum of 50


we seem to be using full-stops on these descriptions in general

richvdh · 2017-12-20T10:24:08Z

api/client-server/users.yaml

@@ -31,7 +31,9 @@ paths:
    post:
      summary: Searches the user directory.
      description: |-
-        This API paginates over search results of the user directory.
+        This API performs a server-side search over all users registered on the server.
+        Searches MXID and displayname case-insesitively for users that you share a room with or that are in public rooms.


MXID isn't actually used very much in the spec (and where it is, I think it's a bug). Suggest 'user ID'.

richvdh · 2017-12-20T10:25:15Z

api/client-server/users.yaml

                  properties:
                    user_id:
                      type: string
                      example: "@foo:bar.com"
+                      description: The MXID of the user.


"The user's matrix user ID"

richvdh · 2017-12-20T10:26:36Z

specification/client_server_api.rst


 {{users_cs_http_api}}


 Profiles
--------
+~~~~~~~~


"Events on Change of Profile Information" is no longer included under "Profiles", which seems odd

richvdh

\o/ perfect

richvdh · 2018-02-20T16:03:54Z

This was added to synapse in matrix-org/synapse#2252, ftr

t3chguy added 2 commits December 17, 2017 23:42

add user_directory

9744519

add changelog entry

1f7d4cd

ara4n requested a review from richvdh December 18, 2017 00:40

richvdh self-assigned this Dec 18, 2017

richvdh requested changes Dec 18, 2017

View reviewed changes

t3chguy and others added 4 commits December 18, 2017 13:30

fix changelog entry

b80f38e

apply points from review

d219cbc

Merge branch 'master' into user_directory

605510e

merge profiles with user directory into user data, also fix typo

3d8fe6e

richvdh reviewed Dec 20, 2017

View reviewed changes

richvdh assigned t3chguy Dec 20, 2017

changes based on Pull Request feedback

784adad

richvdh approved these changes Dec 29, 2017

View reviewed changes

richvdh merged commit 73118b6 into matrix-org:master Dec 29, 2017

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

add user_directory #1096

add user_directory #1096

t3chguy commented Dec 17, 2017

turt2live commented Dec 18, 2017

richvdh commented Dec 18, 2017

richvdh Dec 18, 2017

t3chguy Dec 18, 2017

richvdh Dec 18, 2017

richvdh Dec 18, 2017

richvdh Dec 18, 2017

t3chguy Dec 18, 2017

richvdh Dec 18, 2017

richvdh Dec 18, 2017

richvdh Dec 18, 2017

richvdh Dec 18, 2017

richvdh Dec 18, 2017

richvdh Dec 18, 2017

t3chguy Dec 18, 2017

richvdh Dec 18, 2017

t3chguy commented Dec 18, 2017

richvdh Dec 20, 2017

richvdh Dec 20, 2017

richvdh Dec 20, 2017

richvdh Dec 20, 2017

richvdh Dec 20, 2017

richvdh Dec 20, 2017

richvdh Dec 20, 2017

richvdh Dec 20, 2017

richvdh Dec 20, 2017

richvdh left a comment

richvdh commented Feb 20, 2018

		@@ -1335,6 +1335,13 @@ Listing rooms

		{{list_public_rooms_cs_http_api}}


		Users

add user_directory #1096

add user_directory #1096

Conversation

t3chguy commented Dec 17, 2017

turt2live commented Dec 18, 2017

richvdh commented Dec 18, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

t3chguy commented Dec 18, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

richvdh left a comment

Choose a reason for hiding this comment

richvdh commented Feb 20, 2018