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/data/api/server-server/events.yaml

246 lines
9.3 KiB
YAML

# Copyright 2018-2020 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.
# 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 Federation Events API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v1
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/state/{roomId}":
get:
summary: Get all the state of a given room
description: |-
Retrieves a snapshot of a room's state at a given event.
operationId: getRoomState
security:
- signedRequest: []
parameters:
- in: path
name: roomId
type: string
description: The room ID to get state for.
required: true
x-example: "!abc123:matrix.org"
- in: query
name: event_id
type: string
description: An event ID in the room to retrieve the state at.
required: true
x-example: "$helloworld:matrix.org"
responses:
200:
description: |-
The fully resolved state for the room, prior to considering any state
changes induced by the requested event. Includes the authorization
chain for the events.
schema:
type: object
properties:
auth_chain:
6 years ago
type: array
description: |-
The full set of authorization events that make up the state
of the room, and their authorization events, recursively. Note that
events have a different format depending on the room version -
check the [room version specification](/rooms) for precise event formats.
items:
type: object
title: PDU
description: |-
The [PDUs](/server-server-api/#pdus) contained in the auth chain. The event format
varies depending on the room version - check the [room version specification](/rooms)
for precise event formats.
properties: {}
example:
$ref: "examples/minimal_pdu.json"
pdus:
6 years ago
type: array
description: |-
The fully resolved state of the room at the given event. Note that
events have a different format depending on the room version -
check the [room version specification](/rooms) for precise event formats.
items:
type: object
title: PDU
description: |-
The [PDUs](/server-server-api/#pdus) for the fully resolved state of the room. The event format
varies depending on the room version - check the [room version specification](/rooms)
for precise event formats.
properties: {}
example:
$ref: "examples/minimal_pdu.json"
required: ['auth_chain', 'pdus']
"/state_ids/{roomId}":
get:
summary: Get all the state event IDs of a given room
description: |-
Retrieves a snapshot of a room's state at a given event, in the form of
event IDs. This performs the same function as calling `/state/{roomId}`,
however this returns just the event IDs rather than the full events.
operationId: getRoomStateIds
security:
- signedRequest: []
parameters:
- in: path
name: roomId
type: string
description: The room ID to get state for.
required: true
x-example: "!abc123:matrix.org"
- in: query
name: event_id
type: string
description: An event ID in the room to retrieve the state at.
required: true
x-example: "$helloworld:matrix.org"
responses:
200:
description: |-
The fully resolved state for the room, prior to considering any state
changes induced by the requested event. Includes the authorization
chain for the events.
schema:
type: object
properties:
auth_chain_ids:
6 years ago
type: array
description: |-
The full set of authorization events that make up the state
of the room, and their authorization events, recursively.
items:
type: string
example: ["$an_event:example.org"]
pdu_ids:
6 years ago
type: array
description: |-
The fully resolved state of the room at the given event.
items:
type: string
example: ["$an_event:example.org"]
required: ['auth_chain_ids', 'pdu_ids']
"/event/{eventId}":
get:
summary: Get a single event
description: |-
Retrieves a single event.
operationId: getEvent
security:
- signedRequest: []
parameters:
- in: path
name: eventId
type: string
description: The event ID to get.
required: true
x-example: "$abc123:matrix.org"
responses:
200:
description: A transaction containing a single PDU which is the event requested.
schema:
$ref: "definitions/single_pdu_transaction.yaml"
"/timestamp_to_event/{roomId}":
get:
summary: Get the closest event ID to the given timestamp
x-addedInMatrixVersion: "1.6"
description: |-
Get the ID of the event closest to the given timestamp, in the
direction specified by the `dir` parameter.
This is primarily used when handling the corresponding
[client-server endpoint](/client-server-api/#get_matrixclientv1roomsroomidtimestamp_to_event)
when the server does not have all of the room history, and does not
have an event suitably close to the requested timestamp.
The heuristics for deciding when to ask another homeserver for a closer
event if your homeserver doesn't have something close, are left up to
the homeserver implementation, although the heuristics will probably be
based on whether the closest event is a forward/backward extremity
indicating it's next to a gap of events which are potentially closer.
A good heuristic for which servers to try first is to sort by servers
that have been in the room the longest because they're most likely to
have anything we ask about.
After the local homeserver receives the response, it should determine,
using the `origin_server_ts` property, whether the returned event is
closer to the requested timestamp than the closest event that it could
find locally. If so, it should try to backfill this event via the
[`/event/{event_id}`](#get_matrixfederationv1eventeventid) endpoint so
that it is available to for a client to query.
operationId: getEventByTimestamp
security:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The ID of the room to search
required: true
x-example: "!636q39766251:matrix.org"
- in: query
type: integer
name: ts
description: |-
The timestamp to search from, as given in milliseconds
since the Unix epoch.
required: true
x-example: 1432684800000
- in: query
type: string
enum: [f, b]
name: dir
description: |-
The direction in which to search. `f` for forwards, `b` for backwards.
required: true
x-example: f
responses:
200:
description: |-
An event was found matching the search parameters.
schema:
type: object
properties:
event_id:
type: string
description: |-
The ID of the event found
origin_server_ts:
type: integer
description: |-
The event's timestamp, in milliseconds since the Unix epoch.
required: ['event_id', 'origin_server_ts']
examples:
application/json: {
"event_id": "$143273582443PhrSn:example.org",
"origin_server_ts": 1432735824653
}
404:
description: |-
No event was found.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Unable to find event from 1432684800000 in forward direction"
}
schema:
"$ref": "../client-server/definitions/errors/error.yaml"