matrix-spec-proposals/api/server-server/backfill.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.

swagger: '2.0'
info:
  title: "Matrix Federation Events API"
  version: "1.0.0"
host: localhost:8448
schemes:
  - https
basePath: /_matrix/federation/v1
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  $ref: definitions/security.yaml
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 that preceded it
        are retrieved, up to the total number given by the ``limit``.        
      operationId: backfillRoom
      security:
        - signedRequest: []
      parameters:
        - in: path
          name: roomId
          type: string
          description: The room ID to backfill.
          required: true
          x-example: "!SomeRoom:matrix.org"
        - in: query
          name: v
          type: array
          items:
            type: string
          description: The event IDs to backfill from.
          required: true
          x-example: ["$abc123:matrix.org"]
        - in: query
          name: limit
          type: integer
          description: The maximum number of PDUs to retrieve, including the given events.
          required: true
          x-example: 2
      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.            
          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
          type: string
          description: The room ID to search in.
          required: true
          x-example: "!SomeRoom:matrix.org"
        - in: body
          name: body
          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``.            
          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`_ for precise event formats.                  
                items:
                  type: object
                  title: PDU
            required: ['events']
          examples:
            application/json: {
              "events": [
                {"$ref": "examples/minimal_pdu.json"}
              ]
            }