From 9d474bb8195b3a61b1cad0330aa3f1adec7756e7 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 2 Aug 2018 12:44:54 -0600 Subject: [PATCH 1/2] 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 | 76 +++++++++++++++++++++++++++-- specification/server_server_api.rst | 12 ++++- 2 files changed, 83 insertions(+), 5 deletions(-) diff --git a/api/server-server/events.yaml b/api/server-server/events.yaml index d540085d..f0c3250c 100644 --- a/api/server-server/events.yaml +++ b/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 diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 3bdc5b2b..4a00db98 100644 --- a/specification/server_server_api.rst +++ b/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 ------------------ From 8b7bc603670c2e81c73505b0987690b6b87fa269 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 2 Aug 2018 16:42:03 -0600 Subject: [PATCH 2/2] list -> array --- api/server-server/events.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/api/server-server/events.yaml b/api/server-server/events.yaml index f0c3250c..11c88e8d 100644 --- a/api/server-server/events.yaml +++ b/api/server-server/events.yaml @@ -51,7 +51,7 @@ paths: type: object properties: auth_chain: - type: list + type: array description: |- The full set of authorization events that make up the state of the room, and their authorization events, recursively. @@ -59,7 +59,7 @@ paths: $ref: "definitions/pdu.yaml" example: [{"$ref": "examples/pdu.json"}] pdus: - type: list + type: array description: |- The fully resolved state of the room at the given event. items: @@ -96,7 +96,7 @@ paths: type: object properties: auth_chain_ids: - type: list + type: array description: |- The full set of authorization events that make up the state of the room, and their authorization events, recursively. @@ -104,7 +104,7 @@ paths: type: string example: ["$an_event:domain.com"] pdu_ids: - type: list + type: array description: |- The fully resolved state of the room at the given event. items: