From 97445195f65487337f8ef2438fecca02e2259d3f Mon Sep 17 00:00:00 2001 From: Michael Telatynski <7t3chguy@gmail.com> Date: Sun, 17 Dec 2017 23:42:44 +0000 Subject: [PATCH 1/6] add user_directory --- api/client-server/users.yaml | 93 +++++++++++++++++++++++++++++ specification/client_server_api.rst | 7 +++ 2 files changed, 100 insertions(+) create mode 100644 api/client-server/users.yaml diff --git a/api/client-server/users.yaml b/api/client-server/users.yaml new file mode 100644 index 00000000..e04faac8 --- /dev/null +++ b/api/client-server/users.yaml @@ -0,0 +1,93 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Profile API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/user_directory/search": + post: + summary: Searches the user directory. + description: |- + This API paginates over search results of the user directory. + security: + - accessToken: [] + parameters: + - in: body + name: body + schema: + type: object + properties: + search_term: + type: string + description: The term to search for + example: "foo" + limit: + type: number + description: The maximum number of results to return + example: 10 + required: ["search_term"] + responses: + 200: + description: The results of the paginated search. + examples: + application/json: { + "results": [ + { + "user_id": "@foo:bar.com", + "display_name": "Foo", + "avatar_url": "mxc://bar.com/foo" + } + ], + "limited": false + } + schema: + type: object + required: ["results", "limited"] + properties: + results: + type: array + items: + title: User + type: object + properties: + user_id: + type: string + example: "@foo:bar.com" + display_name: + type: string + example: "Foo" + avatar_url: + type: string + example: "mxc://bar.com/foo" + limited: + type: boolean + description: Indicates if the result list has been truncated by the limit. + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/error.yaml" + tags: + - User data diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index e68aea43..2586041d 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1335,6 +1335,13 @@ Listing rooms {{list_public_rooms_cs_http_api}} + +Users +----- + +{{users_cs_http_api}} + + Profiles -------- From 1f7d4cd9d07891ad2f122faa1109ffa4758b38da Mon Sep 17 00:00:00 2001 From: Michael Telatynski <7t3chguy@gmail.com> Date: Sun, 17 Dec 2017 23:45:55 +0000 Subject: [PATCH 2/6] add changelog entry --- changelogs/client_server.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index 4a26c302..faae2476 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -76,6 +76,9 @@ r0.3.0 - ``GET /media/{version}/preview_url`` (`#1064 `_). + - ``POST /user_directory/search`` + (`#1096 `_). + - Spec clarifications: - Add endpoints and logic for invites and third-party invites to the federation From b80f38e11b62ef0ca35e9e8acb557aba867036c0 Mon Sep 17 00:00:00 2001 From: Michael Telatynski <7t3chguy@gmail.com> Date: Mon, 18 Dec 2017 13:30:37 +0000 Subject: [PATCH 3/6] fix changelog entry --- changelogs/client_server.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index faae2476..13d895fa 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -1,7 +1,12 @@ Unreleased changes ================== -No changes as yet. +- Changes to the API which will be backwards-compatible for clients: + + - New endpoints: + + - ``POST /user_directory/search`` + (`#1096 `_). r0.3.0 ====== @@ -76,9 +81,6 @@ r0.3.0 - ``GET /media/{version}/preview_url`` (`#1064 `_). - - ``POST /user_directory/search`` - (`#1096 `_). - - Spec clarifications: - Add endpoints and logic for invites and third-party invites to the federation From d219cbc97886d23700bab26486dff6079f629bcd Mon Sep 17 00:00:00 2001 From: Michael Telatynski <7t3chguy@gmail.com> Date: Mon, 18 Dec 2017 16:54:11 +0000 Subject: [PATCH 4/6] apply points from review --- api/client-server/users.yaml | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/api/client-server/users.yaml b/api/client-server/users.yaml index e04faac8..ff24967a 100644 --- a/api/client-server/users.yaml +++ b/api/client-server/users.yaml @@ -1,4 +1,4 @@ -# Copyright 2016 OpenMarket Ltd +# Copyright 2017 New Vector Ltd # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -13,7 +13,7 @@ # limitations under the License. swagger: '2.0' info: - title: "Matrix Client-Server Profile API" + title: "Matrix Client-Server User Directory API" version: "1.0.0" host: localhost:8008 schemes: @@ -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. + operationId: postUserDirectorySearch security: - accessToken: [] parameters: @@ -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 example: 10 required: ["search_term"] responses: 200: - description: The results of the paginated search. + description: The results of the search. examples: application/json: { "results": [ @@ -69,9 +71,11 @@ paths: properties: results: type: array + description: Ordered by rank and then whether or not profile info is available. items: title: User type: object + require: ["user_id"] properties: user_id: type: string From 3d8fe6e0903a0071f1d2080a9813d04f70d69541 Mon Sep 17 00:00:00 2001 From: Michael Telatynski <7t3chguy@gmail.com> Date: Mon, 18 Dec 2017 17:01:52 +0000 Subject: [PATCH 5/6] merge profiles with user directory into user data, also fix typo --- api/client-server/users.yaml | 5 ++++- specification/client_server_api.rst | 9 ++++++--- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/api/client-server/users.yaml b/api/client-server/users.yaml index ff24967a..cecf9424 100644 --- a/api/client-server/users.yaml +++ b/api/client-server/users.yaml @@ -75,17 +75,20 @@ paths: items: title: User type: object - require: ["user_id"] + required: ["user_id"] properties: user_id: type: string example: "@foo:bar.com" + description: The MXID of the user. display_name: type: string example: "Foo" + description: The display name of the user, if one exists. avatar_url: type: string example: "mxc://bar.com/foo" + description: The avatar url, as an MXC, if one exists. limited: type: boolean description: Indicates if the result list has been truncated by the limit. diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 2586041d..e40aa6f1 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1336,14 +1336,17 @@ Listing rooms {{list_public_rooms_cs_http_api}} -Users ------ +User Data +--------- + +User Directory +~~~~~~~~~~~~~~ {{users_cs_http_api}} Profiles --------- +~~~~~~~~ {{profile_cs_http_api}} From 784adade9bc0332359d815036c53722aed82e3b4 Mon Sep 17 00:00:00 2001 From: Michael Telatynski <7t3chguy@gmail.com> Date: Thu, 21 Dec 2017 17:45:26 +0000 Subject: [PATCH 6/6] changes based on Pull Request feedback --- api/client-server/users.yaml | 8 ++++---- specification/client_server_api.rst | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/api/client-server/users.yaml b/api/client-server/users.yaml index cecf9424..1734e3bb 100644 --- a/api/client-server/users.yaml +++ b/api/client-server/users.yaml @@ -32,8 +32,8 @@ paths: summary: Searches the user directory. description: |- 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 + It searches user ID and displayname case-insensitively for users that you share a room with or that are in public rooms. + operationId: searchUserDirectory security: - accessToken: [] parameters: @@ -48,7 +48,7 @@ paths: example: "foo" limit: type: number - description: The maximum number of results to return (10 if omitted), with a maximum of 50 + description: The maximum number of results to return (Defaults to 10). example: 10 required: ["search_term"] responses: @@ -80,7 +80,7 @@ paths: user_id: type: string example: "@foo:bar.com" - description: The MXID of the user. + description: The user's matrix user ID. display_name: type: string example: "Foo" diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index e40aa6f1..326ff282 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1351,7 +1351,7 @@ Profiles {{profile_cs_http_api}} Events on Change of Profile Information -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ++++++++++++++++++++++++++++++++++++++++ Because the profile display name and avatar information are likely to be used in many places of a client's display, changes to these fields cause an automatic propagation event to occur, informing likely-interested parties of the new