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/backfill.yaml

167 lines
5.9 KiB
YAML

# Copyright 2018 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.
openapi: 3.1.0
info:
title: Matrix Federation Events API
version: 1.0.0
paths:
"/backfill/{roomId}":
get:
summary: Retrieves the events which precede the given event
description: |-
Retrieves a sliding-window history of previous PDUs that occurred in the given room.
Starting from the PDU ID(s) given in the `v` argument, the PDUs given in `v` and
the PDUs that preceded them are retrieved, up to the total number given by the `limit`.
operationId: backfillRoom
security:
- signedRequest: []
parameters:
- in: path
name: roomId
description: The room ID to backfill.
required: true
example: "!SomeRoom:matrix.org"
schema:
type: string
- in: query
name: v
description: The event IDs to backfill from.
required: true
example:
- $abc123:matrix.org
schema:
type: array
items:
type: string
- in: query
name: limit
description: The maximum number of PDUs to retrieve, including the given events.
required: true
example: 2
schema:
type: integer
responses:
"200":
description: |-
A transaction containing the PDUs that preceded the given event(s), including the given
event(s), up to the given limit.
**Note:**
Though the PDU definitions require that `prev_events` and `auth_events` be limited
in number, the response of backfill MUST NOT be validated on these specific restrictions.
Due to historical reasons, it is possible that events which were previously accepted
would now be rejected by these limitations. The events should be rejected per usual by
the `/send`, `/get_missing_events`, and remaining endpoints.
content:
application/json:
schema:
$ref: definitions/unlimited_pdu_transaction.yaml
"/get_missing_events/{roomId}":
post:
summary: Retrieves events that the sender is missing
description: |-
Retrieves previous events that the sender is missing. This is done by doing a breadth-first
walk of the `prev_events` for the `latest_events`, ignoring any events in `earliest_events`
and stopping at the `limit`.
operationId: getMissingPreviousEvents
security:
- signedRequest: []
parameters:
- in: path
name: roomId
description: The room ID to search in.
required: true
example: "!SomeRoom:matrix.org"
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
limit:
type: integer
description: The maximum number of events to retrieve. Defaults to 10.
example: 10
min_depth:
type: integer
description: The minimum depth of events to retrieve. Defaults to 0.
example: 0
earliest_events:
type: array
description: |-
The latest event IDs that the sender already has. These are skipped when retrieving
the previous events of `latest_events`.
items:
type: string
example:
- $missing_event:example.org
latest_events:
type: array
description: The event IDs to retrieve the previous events for.
items:
type: string
example:
- $event_that_has_the_missing_event_as_a_previous_event:example.org
required:
- earliest_events
- latest_events
responses:
"200":
description: |-
The previous events for `latest_events`, excluding any `earliest_events`, up to the
provided `limit`.
content:
application/json:
schema:
type: object
properties:
events:
type: array
description: |-
The missing events. The event format varies depending on the room version - check
the [room version specification](/rooms) for precise event formats.
items:
type: object
title: PDU
required:
- events
examples:
response:
value: {
"events": [
{
"$ref": "examples/minimal_pdu.json"
}
]
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8448
basePath:
default: /_matrix/federation/v1
components:
securitySchemes:
signedRequest:
$ref: definitions/security.yaml#/signedRequest