mirror of
https://github.com/matrix-org/matrix-spec
synced 2025-12-24 09:58:38 +01:00
820704a16a
According the the openapi spec, examples for responses and schemas should be raw objects rather than being json strings. (It's unclear what non-json examples should look like...). The swagger UI used to support json strings, but no longer does. In short, let's turn the json strings into their raw formats.
343 lines
15 KiB
YAML
343 lines
15 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.
|
|
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"
|
|
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
|
|
description: |-
|
|
This takes a `filter <https://matrix.org/docs/spec/%CLIENT_RELEASE_LABEL%/client_server.html#filtering>`_.
|
|
order_by:
|
|
title: "Ordering"
|
|
type: string
|
|
enum: ["recent", "rank"]
|
|
description: "The order in which to search for results."
|
|
event_context:
|
|
title: "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.
|
|
after_limit:
|
|
type: integer
|
|
title: "After limit"
|
|
description: |-
|
|
How many events after the result are
|
|
returned.
|
|
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.
|
|
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: 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: An approximate count of the total number of results found.
|
|
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.
|
|
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``.
|
|
additionalProperties:
|
|
type: array
|
|
title: Room State
|
|
items:
|
|
"$ref": "definitions/event-schemas/schema/core-event-schema/state_event.yaml"
|
|
groups:
|
|
type: object
|
|
title: Groups
|
|
description: Any groups that were requested.
|
|
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"
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"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/error.yaml"
|
|
tags:
|
|
- Search
|