From cda88f3b3debfcacb4ea2ec37ed8309d3090dd8e Mon Sep 17 00:00:00 2001
From: Travis Ralston <travpc@gmail.com>
Date: Thu, 2 Aug 2018 23:18:08 -0600
Subject: [PATCH] Document /get_missing_events

Fixes https://github.com/matrix-org/matrix-doc/issues/1385
---
 api/server-server/backfill.yaml     | 66 ++++++++++++++++++++++++++++-
 specification/server_server_api.rst |  8 +++-
 2 files changed, 71 insertions(+), 3 deletions(-)

diff --git a/api/server-server/backfill.yaml b/api/server-server/backfill.yaml
index f83057ae..072b28d1 100644
--- a/api/server-server/backfill.yaml
+++ b/api/server-server/backfill.yaml
@@ -27,7 +27,7 @@ paths:
     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.
+        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
@@ -75,3 +75,67 @@ paths:
                 },
               ]
             }
+  "/get_missing_events/{roomId}":
+    post:
+      summary: Retrieves events that the sender is missing
+      description: |-
+        Retrieves the previous events that the sender is missing for a given set of
+        events.
+      operationId: getMissingPreviousEvents
+      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 events the sender is missing. The response will only contain events
+                  that didn't happen before these events.
+                items:
+                  type: string
+                example: ["$missing_event:domain.com"]
+              latest_events:
+                type: array
+                description: |-
+                  The events that the sender has, but does not have previous events for.
+                items:
+                  type: string
+                example: ["$event_that_has_the_missing_event_as_a_previous_event:domain.com"]
+            required: ['earliest_events', 'latest_events']
+      responses:
+        200:
+          description: |-
+            The events that happened after the ``earliest_events`` which are also previous
+            to the ``latest_events`` and have the minimum depth specified. Does not include
+            any of the events in the request.
+          schema:
+            type: object
+            properties:
+              events:
+                type: array
+                description: The missing events.
+                items:
+                  $ref: definitions/pdu.yaml
+            required: ['events']
+          examples:
+            application/json: {
+              "events": [
+                {"$ref": "examples/pdu.json"}
+              ]
+            }
diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst
index 090885bc..d7a22e72 100644
--- a/specification/server_server_api.rst
+++ b/specification/server_server_api.rst
@@ -836,8 +836,8 @@ following keys:
     here. What purpose does it serve expanding them out in full, when surely
     they'll appear in the state anyway?
 
-Backfilling
------------
+Backfilling and retrieving missing events
+-----------------------------------------
 
 Once a homeserver has joined a room, it receives all the events emitted by
 other homeservers in that room, and is thus aware of the entire history of the
@@ -855,6 +855,10 @@ 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.
 
+Similar to backfilling a room's history, a server may not have all the events
+in the graph. That server may use the ``/get_missing_events`` API to acquire
+the events it is missing.
+
 .. TODO-spec
   Specify (or remark that it is unspecified) how the server handles divergent
   history. DFS? BFS? Anything weirder?