wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge pull request #1472 from turt2live/travis/s2s/get-event

Browse source 
Document event retrieval endpoints in more detail
This commit is contained in:
Travis Ralston 2018-08-03 08:53:49 -06:00 • committed by GitHub
commit 329baa1b9d
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 83 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

76
api/server-server/events.yaml
View file

@ -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: array
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: array
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: array
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: array
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

13
specification/server_server_api.rst
View file

@ -569,9 +569,6 @@ All these URLs are name-spaced within a prefix of::
/_matrix/federation/v1/...
{{events_ss_http_api}}
{{query_general_ss_http_api}}
Joining Rooms
@ -699,6 +696,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
------------------