From 5aef545128b08b12c44a73fa92b903caf162db48 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 1 Aug 2018 13:31:23 -0600 Subject: [PATCH] Improve documentation for backfilling rooms There's not a whole lot to improve here - most of the changes are about reorganization and minor clarifications. --- api/server-server/backfill.yaml | 77 +++++++++++++++++++++++++++++ api/server-server/events.yaml | 32 ------------ specification/server_server_api.rst | 27 +++------- 3 files changed, 83 insertions(+), 53 deletions(-) create mode 100644 api/server-server/backfill.yaml diff --git a/api/server-server/backfill.yaml b/api/server-server/backfill.yaml new file mode 100644 index 000000000..f83057ae0 --- /dev/null +++ b/api/server-server/backfill.yaml @@ -0,0 +1,77 @@ +# 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 +produces: + - application/json +paths: + "/backfill/{roomId}": + get: + summary: Retrieves the events which precede the given event + description: |- + Retreives 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 + 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. + schema: + $ref: "definitions/transaction.yaml" + # Override the example to show the response of the request a bit better + examples: + application/json: { + "$ref": "examples/transaction.json", + "pdus": [ + { + "$ref": "pdu.json", + "room_id": "!SomeRoom:matrix.org", + "event_id": "$abc123:matrix.org" + }, + { + "$ref": "pdu.json", + "room_id": "!SomeRoom:matrix.org" + }, + ] + } diff --git a/api/server-server/events.yaml b/api/server-server/events.yaml index d540085d2..3b48f15c1 100644 --- a/api/server-server/events.yaml +++ b/api/server-server/events.yaml @@ -59,35 +59,3 @@ paths: description: A transaction containing a single PDU which is the event requested. schema: $ref: "definitions/transaction.yaml" - "/backfill/{roomId}": - get: - summary: Retrieves the events which precede the given event - description: |- - Retreives 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 - parameters: - - in: path - name: roomId - type: string - description: The room ID to backfill. - required: true - x-example: "!abc123:matrix.org" - - in: query - name: v - type: string # TODO: The description says this is plural - figure out how to specify multiple, and spec it - description: The event ID to backfill from. - required: true - x-example: "$abc123:matrix.org" - - in: query - name: limit - type: integer - description: The maximum number of events to retrieve. - required: true - x-example: 10 - responses: - 200: - description: A transaction containing the PDUs that preceded the given event(s). - schema: - $ref: "definitions/transaction.yaml" diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index f1825f270..090885bcf 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -850,32 +850,17 @@ To cover this case, the federation API provides a server-to-server analog of the ``/messages`` client API, allowing one homeserver to fetch history from another. This is the ``/backfill`` API. -To request more history, the requesting homeserver picks another homeserver -that it thinks may have more (most likely this should be a homeserver for some -of the existing users in the room at the earliest point in history it has -currently), and makes a ``/backfill`` request. The parameters of this request -give an event ID that the requesting homeserver wishes to obtain, and a number -specifying how many more events of history before that one to return at most. - -The response to this request is an object with the following keys: - -======================== ============ ========================================= - Key Type Description -======================== ============ ========================================= -``pdus`` List A list of events. -``origin`` String The name of the resident homeserver. -``origin_server_ts`` Integer A timestamp added by the resident - homeserver. -======================== ============ ========================================= - -The list of events given in ``pdus`` is returned in reverse chronological -order; having the most recent event first (i.e. the event whose event ID is -that requested by the requester in the ``v`` parameter). +To request more history, the requesting homeserver picks another homeserver +that it thinks may have more (most likely this should be a homeserver for +some of the existing users in the room at the earliest point in history it +has currently), and makes a ``/backfill`` request. .. TODO-spec Specify (or remark that it is unspecified) how the server handles divergent history. DFS? BFS? Anything weirder? +{{backfill_ss_http_api}} + Inviting to a room ------------------