diff --git a/api/client-server/v1/search.yaml b/api/client-server/v1/search.yaml new file mode 100644 index 00000000..885e62b3 --- /dev/null +++ b/api/client-server/v1/search.yaml @@ -0,0 +1,140 @@ +swagger: '2.0' +info: + title: "Matrix Client-Server v1 Search API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/api/v1 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + accessToken: + type: apiKey + description: The user_id or application service access_token + name: access_token + in: query +paths: + "/search": + post: + summary: Search server side for things. + description: |- + Performs a full text search across different categories. + security: + - accessToken: [] + parameters: + - in: body + name: body + schema: + type: object + example: |- + { + "search_categories": { + "room_events": { + "keys": [ + "content.body" + ], + "search_term": "martians and men" + } + } + } + properties: + search_categories: + type: object + title: "Categories" + description: Describes which categories to search in and + their criteria. + properties: + room_events: + type: object + title: "Room Events" + description: Mapping of category name to search criteria. + properties: + search_term: + type: string + description: The string to search events for + keys: + type: array + items: + type: string + enum: ["content.body", "content.name", "content.topic"] + description: The keys to search. Defaults to all. + required: ["search_term"] + required: ["search_categories"] + responses: + 200: + description: Results of the search. + schema: + type: object + title: Results + required: ["search_categories"] + properties: + search_categories: + type: object + title: Categories + description: Describes which categories to search in and + their criteria. + properties: + room_events: + type: object + title: Room Event Results + description: Mapping of category name to search criteria. + properties: + count: + type: number + description: Total number of results found + results: + type: object + title: Results + description: Mapping of event_id to result. + additionalProperties: + type: object + title: Result + description: The result object. + properties: + rank: + type: number + description: A number that describes how closely + this result matches the search. Higher is + closer. + result: + type: object + title: Event + description: The event that matched. + allOf: + - "$ref": "core-event-schema/room_event.json" + examples: + application/json: |- + { + "search_categories": { + "room_events": { + "count": 24, + "results": { + "$144429830826TWwbB:localhost": { + "rank": 0.00424866, + "result": { + "age": 526228296, + "content": { + "body": "Test content", + "msgtype": "m.text" + }, + "event_id": "$144429830826TWwbB:localhost", + "origin_server_ts": 1444298308034, + "room_id": "!qPewotXpIctQySfjSy:localhost", + "type": "m.room.message", + "user_id": "@test:localhost" + } + } + } + } + } + } + 400: + description: Part of the request was invalid. + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/error.yaml" diff --git a/specification/feature_profiles.rst b/specification/feature_profiles.rst index 6c11dd2f..f79b92c5 100644 --- a/specification/feature_profiles.rst +++ b/specification/feature_profiles.rst @@ -26,6 +26,7 @@ Summary `Content Repository`_ Required Required Required Optional Optional `Managing History Visibility`_ Required Required Required Required Optional `End-to-End Encryption`_ Optional Optional Optional Optional Optional + `Server Side Search`_ Optional Optional Optional Optional Optional ===================================== ========== ========== ========== ========== ========== *Please see each module for more details on what clients need to implement.* @@ -39,6 +40,7 @@ Summary .. _VoIP: `module:voip`_ .. _Content Repository: `module:content`_ .. _Managing History Visibility: `module:history-visibility`_ +.. _Server Side Search: `module:search`_ Clients ------- diff --git a/specification/modules/search.rst b/specification/modules/search.rst new file mode 100644 index 00000000..089953d2 --- /dev/null +++ b/specification/modules/search.rst @@ -0,0 +1,46 @@ +Server Side Search +================== + +.. _module:search: + +The search API allows clients to perform full text search across events in all +rooms that the user has been in, including those that they have left. Only +events that the user is allowed to see will be searched, e.g. it won't include +events in rooms that happened after you left. + +Client behaviour +---------------- +{{search_http_api}} + +Search Categories +----------------- + +The search API allows clients to search in different categories of items. +Currently the only specified category is ``room_events``. + +``room_events`` +~~~~~~~~~~~~~~~ + +This category covers all events that the user is allowed to see, including +events in rooms that they have left. The search is performed on certain keys of +certain event types. + +The supported keys to search over are: + +- ``content.body`` in ``m.room.message`` +- ``content.name`` in ``m.room.name`` +- ``content.topic`` in ``m.room.topic`` + +The search will *not* include rooms that are end to end encrypted. + +The results include a ``rank`` key that can be used to sort the results by +revelancy. The higher the ``rank`` the more relevant the result is. + +The value of ``count`` may not match the number of results. For example due to +the search query matching 1000s of results and the server truncating the +response. + +Security considerations +----------------------- +The server must only return results that the user has permission to see. + diff --git a/specification/targets.yaml b/specification/targets.yaml index 4ac34ae3..2482dcfd 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -24,6 +24,8 @@ groups: # reusable blobs of files when prefixed with 'group:' - modules/history_visibility.rst - modules/push.rst - modules/third_party_invites.rst + - modules/search.rst + title_styles: ["=", "-", "~", "+", "^", "`"]