Merge branch 'master' into rav/send_events_api
This commit is contained in:
Richard van der Hoff
commit
587a8ba7ce
10 changed files with 197 additions and 1 deletions
140
api/client-server/v1/search.yaml
Normal file
140
api/client-server/v1/search.yaml
Normal file
|
|
@ -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"
|
||||
5
scripts/css/blockquote.css
Normal file
5
scripts/css/blockquote.css
Normal file
|
|
@ -0,0 +1,5 @@
|
|||
blockquote {
|
||||
margin: 20px 0 30px;
|
||||
border-left: 5px solid;
|
||||
padding-left: 20px;
|
||||
}
|
||||
|
|
@ -15,7 +15,7 @@ import yaml
|
|||
os.chdir(os.path.dirname(os.path.abspath(__file__)))
|
||||
|
||||
stylesheets = {
|
||||
"stylesheet_path": ["basic.css", "nature.css", "codehighlight.css"]
|
||||
"stylesheet_path": glob.glob("css/*.css"),
|
||||
}
|
||||
|
||||
VERBOSE = False
|
||||
|
|
|
|||
|
|
@ -365,6 +365,7 @@ func main() {
|
|||
"Kegsay": true,
|
||||
"NegativeMjark": true,
|
||||
"richvdh": true,
|
||||
"leonerd": true,
|
||||
}
|
||||
rand.Seed(time.Now().Unix())
|
||||
masterCloneDir, err := gitClone(matrixDocCloneURL, false)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
-------
|
||||
|
|
|
|||
46
specification/modules/search.rst
Normal file
46
specification/modules/search.rst
Normal file
|
|
@ -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.
|
||||
|
||||
|
|
@ -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: ["=", "-", "~", "+", "^", "`"]
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue