# 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:
    $ref: definitions/security.yaml