Document event retrieval endpoints in more detail

This also adds a previously-undocumented endpoint: /state_ids

Backfill is technically not part of this section, however it is being left untouched to make the merge with #1469 easier (which moves it out of the file).

Reference material:
* Some calls to synapse on these endpoints with a relatively simple private room.

api/server-server/events.yaml

@@ -27,7 +27,7 @@ paths:
     get:
       summary: Get all the state of a given room
       description: |-
-        Retrieves a snapshot of the entire current state of the given room.
+        Retrieves a snapshot of a room's state at a given event.
       operationId: getRoomState
       parameters:
         - in: path
@@ -36,11 +36,81 @@ paths:
           description: The room ID to get state for.
           required: true
           x-example: "!abc123:matrix.org"
+        - in: query
+          name: event_id
+          type: string
+          description: An event ID in the room to retrieve the state at.
+          required: true
+          x-example: "$helloworld:matrix.org"
       responses:
         200:
-          description: The room state for the room (kept under ``pdus``).
+          description: |-
+            The fully resolved state for the room, including the authorization
+            chain for the events.
           schema:
-            $ref: "definitions/transaction.yaml"
+            type: object
+            properties:
+              auth_chain:
+                type: list
+                description: |-
+                  The full set of authorization events that make up the state
+                  of the room, and their authorization events, recursively.
+                items:
+                  $ref: "definitions/pdu.yaml"
+                example: [{"$ref": "examples/pdu.json"}]
+              pdus:
+                type: list
+                description: |-
+                  The fully resolved state of the room at the given event.
+                items:
+                  $ref: "definitions/pdu.yaml"
+                example: [{"$ref": "examples/pdu.json"}]
+            required: ['auth_chain', 'pdus']
+  "/state_ids/{roomId}":
+    get:
+      summary: Get all the state event IDs of a given room
+      description: |-
+        Retrieves a snapshot of a room's state at a given event, in the form of
+        event IDs. This performs the same function as calling ``/state/{roomId}``,
+        however this returns just the event IDs rather than the full events.
+      operationId: getRoomStateIds
+      parameters:
+        - in: path
+          name: roomId
+          type: string
+          description: The room ID to get state for.
+          required: true
+          x-example: "!abc123:matrix.org"
+        - in: query
+          name: event_id
+          type: string
+          description: An event ID in the room to retrieve the state at.
+          required: true
+          x-example: "$helloworld:matrix.org"
+      responses:
+        200:
+          description: |-
+            The fully resolved state for the room, including the authorization
+            chain for the events.
+          schema:
+            type: object
+            properties:
+              auth_chain_ids:
+                type: list
+                description: |-
+                  The full set of authorization events that make up the state
+                  of the room, and their authorization events, recursively.
+                items:
+                  type: string
+                example: ["$an_event:domain.com"]
+              pdu_ids:
+                type: list
+                description: |-
+                  The fully resolved state of the room at the given event.
+                items:
+                  type: string
+                example: ["$an_event:domain.com"]
+            required: ['auth_chain_ids', 'pdu_ids']
   "/event/{eventId}":
     get:
       summary: Get a single event

specification/server_server_api.rst

@@ -606,8 +606,6 @@ All these URLs are name-spaced within a prefix of::
 
 {{transactions_ss_http_api}}
 
-{{events_ss_http_api}}
-
 {{query_general_ss_http_api}}
 
 
@@ -798,6 +796,16 @@ that requested by the requester in the ``v`` parameter).
   Specify (or remark that it is unspecified) how the server handles divergent
   history. DFS? BFS? Anything weirder?
 
+Retriving events
+----------------
+
+In some circumstances, a homeserver may be missing a particular event or information
+about the room which cannot be easily determined from backfilling. These APIs provide
+homeservers with the option of getting events and the state of the room at a given
+point in the timeline.
+
+{{events_ss_http_api}}
+
 Inviting to a room
 ------------------