You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
matrix-spec-proposals/api/client-server/search.yaml

374 lines
16 KiB
YAML

# 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 Search 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:
"/search":
post:
summary: Perform a server-side search.
description: |-
Performs a full text search across different categories.
operationId: search
security:
- accessToken: []
parameters:
- in: query
name: next_batch
type: string
description: |-
The point to return events from. If given, this should be a
``next_batch`` result from a previous call to this endpoint.
x-example: "YWxsCgpOb25lLDM1ODcwOA"
- in: body
name: body
schema:
type: object
example: {
"search_categories": {
"room_events": {
"keys": [
"content.body"
],
"search_term": "martians and men",
"order_by": "recent",
"groupings": {
"group_by": [
{
"key": "room_id"
}
]
}
}
}
}
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 Criteria
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.
filter:
type: object
title: Filter
# Within the C-S spec document, `filter`_ is picked up
# as a link to the filtering section. In OpenAPI 3.0,
# we could use the link feature, but we're still on 2.0
# for now :/
description: |-
This takes a `filter`_.
$ref: "definitions/room_event_filter.yaml"
order_by:
title: "Ordering"
type: string
enum: ["recent", "rank"]
description: |-
The order in which to search for results.
By default, this is ``"rank"``.
event_context:
title: Include Event Context
type: object
description: |-
Configures whether any context for the events
returned are included in the response.
properties:
before_limit:
type: integer
title: "Before limit"
description: |-
How many events before the result are
returned. By default, this is ``5``.
after_limit:
type: integer
title: "After limit"
description: |-
How many events after the result are
returned. By default, this is ``5``.
include_profile:
type: boolean
title: "Return profile information"
description: |-
Requests that the server returns the
historic profile information for the users
that sent the events that were returned.
By default, this is ``false``.
include_state:
type: boolean
title: Include current state
description: |-
Requests the server return the current state for
each room returned.
groupings:
type: object
title: Groupings
description: |-
Requests that the server partitions the result set
based on the provided list of keys.
properties:
group_by:
type: array
title: Groups
description: List of groups to request.
items:
type: object
title: Group
description: Configuration for group.
properties:
key:
type: string
title: Group Key
description: |-
Key that defines the group.
enum: ["room_id", "sender"]
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: Result Categories
description: Describes which categories to search in and
their criteria.
properties:
room_events:
type: object
title: Result Room Events
description: Mapping of category name to search criteria.
properties:
count:
type: integer
description: An approximate count of the total number of results found.
highlights:
type: array
title: Highlights
description: List of words which should be highlighted, useful for stemming which may change the query terms.
items:
type: string
results:
type: array
title: Results
description: List of results in the requested order.
items:
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.
"$ref": "definitions/event-schemas/schema/core-event-schema/room_event.yaml"
context:
type: object
title: Event Context
description: Context for result, if requested.
properties:
start:
type: string
title: Start Token
description: |-
Pagination token for the start of the chunk
end:
type: string
title: End Token
description: |-
Pagination token for the end of the chunk
profile_info:
type: object
title: Profile Information
description: |-
The historic profile information of the
users that sent the events returned.
The ``string`` key is the user ID for which
the profile belongs to.
additionalProperties:
type: object
title: User Profile
properties:
displayname:
type: string
title: Display name
avatar_url:
type: string
title: Avatar Url
events_before:
type: array
title: Events Before
description: Events just before the result.
items:
title: Event
type: object
"$ref": "definitions/event-schemas/schema/core-event-schema/room_event.yaml"
events_after:
type: array
title: Events After
description: Events just after the result.
items:
title: Event
type: object
"$ref": "definitions/event-schemas/schema/core-event-schema/room_event.yaml"
state:
type: object
title: Current state
description: |-
The current state for every room in the results.
This is included if the request had the
``include_state`` key set with a value of ``true``.
The ``string`` key is the room ID for which the ``State
Event`` array belongs to.
additionalProperties:
type: array
title: Room State
items:
type: object
"$ref": "definitions/event-schemas/schema/core-event-schema/state_event.yaml"
groups:
type: object
title: Groups
description: |-
Any groups that were requested.
The outer ``string`` key is the group key requested (eg: ``room_id``
or ``sender``). The inner ``string`` key is the grouped value (eg:
a room's ID or a user's ID).
additionalProperties:
type: object
title: Group Key
description: The results for a given group.
additionalProperties:
type: object
title: Group Value
description: |-
The results for a particular group value.
properties:
next_batch:
type: string
title: Next Batch in Group
description: |-
Token that can be used to get the next batch
of results in the group, by passing as the
`next_batch` parameter to the next call. If
this field is absent, there are no more
results in this group.
order:
type: integer
title: Group Order
description: |-
Key that can be used to order different
groups.
results:
type: array
description: |-
Which results are in this group.
items:
type: string
title: Result Event ID
next_batch:
type: string
title: Next Batch
description: |-
Token that can be used to get the next batch of
results, by passing as the `next_batch` parameter to
the next call. If this field is absent, there are no
more results.
examples:
application/json: {
"search_categories": {
"room_events": {
"groups": {
"room_id": {
"!qPewotXpIctQySfjSy:localhost": {
"order": 1,
"next_batch": "BdgFsdfHSf-dsFD",
"results": [
"$144429830826TWwbB:localhost"
]
}
}
},
"highlights": [
"martians",
"men"
],
"next_batch": "5FdgFsd234dfgsdfFD",
"count": 1224,
"results": [
{
"rank": 0.00424866,
"result": {
"age": 526228296,
"content": {
"body": "Test content martians and men",
"msgtype": "m.text"
},
"event_id": "$144429830826TWwbB:localhost",
"origin_server_ts": 1444298308034,
"room_id": "!qPewotXpIctQySfjSy:localhost",
"type": "m.room.message",
"sender": "@test:localhost"
}
}
]
}
}
}
400:
description: Part of the request was invalid.
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Search