147 lines
5.4 KiB
Markdown
147 lines
5.4 KiB
Markdown
# MSC2695: Get event by ID over federation
|
|
|
|
Currently, there is no clear client-server API to retrieve a single event by the
|
|
event ID alone. There is the deprecated [`GET
|
|
/_matrix/client/r0/events/{eventId}`](https://matrix.org/docs/spec/client_server/latest#deprecated-get-matrix-client-r0-events-eventid),
|
|
but this could be removed some day and also does not support accessing events on
|
|
remote servers over federation.
|
|
|
|
As part of revising matrix.to URI syntax in
|
|
[MSC2644](https://github.com/matrix-org/matrix-doc/pull/2644), there is
|
|
interest in supporting permalinks to events that contain the event ID without
|
|
the room ID. In order for such links to be useful, we need a clear path to get
|
|
that event using the event ID without having the room ID.
|
|
|
|
While the matrix.to interstitial UI is the primary initial use case, other tools
|
|
that wish to preview or display a single event should benefit from having such
|
|
an API as well.
|
|
|
|
## Proposal
|
|
|
|
This proposal un-deprecates and extends the existing `GET
|
|
/_matrix/client/r0/events/{eventId}` API to address this need.
|
|
|
|
### API details
|
|
|
|
`GET /_matrix/client/r0/events/{eventId}`
|
|
|
|
Get a single event based on `eventId`.
|
|
|
|
You must have permission to retrieve this event e.g. by being a member in the
|
|
room for this event in order to access the full event content. If the room is
|
|
`world_readable`, the full event content can be retrieved without
|
|
authentication.
|
|
|
|
For all events, even those for which you do not have access, this API will
|
|
always return at least the `event_id` and `room_id` keys (assuming the event can
|
|
be found locally or via one of the provided servers). In this way, this API can
|
|
always be used to determine the room ID of an event, as long as a server in the
|
|
room is known.
|
|
|
|
If the event is not known to the local server, it will attempt to retrieve the
|
|
event via federation (e.g. `GET /_matrix/federation/v1/event/{eventId}`) from
|
|
the provided servers in the `server_name` query parameter.
|
|
|
|
* Authentication
|
|
* Optional
|
|
* If called without authentication, then only events in `world_readable` rooms
|
|
are accessible.
|
|
* Rate-limited
|
|
* Since this revised version supports unauthenticated requests, rate limiting
|
|
is important to limit abuse and DoS attacks
|
|
* Path parameters
|
|
* `eventId` (`string`): **Required.** The event ID to get.
|
|
* Query parameters
|
|
* `server_name` (`[string]`): The servers to attempt to get the event from if
|
|
unknown to the local server. One of the servers must be participating in the
|
|
room.
|
|
|
|
#### Example request
|
|
|
|
`GET
|
|
/_matrix/client/r0/events/%24Woq2vwLy8mNukf7e8oz61GxT5gpMmr_asNojhb56-wU?server_name=matrix.org&server_name=example.org
|
|
HTTP/1.1`
|
|
|
|
#### Example responses
|
|
|
|
If the event is found and is either `world_readable` or the authenticated user
|
|
has permission to retrieve it, then the full event content is returned with
|
|
status code 200:
|
|
|
|
```
|
|
{
|
|
"content": {
|
|
"body": "This is an example text message",
|
|
"msgtype": "m.text",
|
|
"format": "org.matrix.custom.html",
|
|
"formatted_body": "<b>This is an example text message</b>"
|
|
},
|
|
"type": "m.room.message",
|
|
"event_id": "$Woq2vwLy8mNukf7e8oz61GxT5gpMmr_asNojhb56-wU",
|
|
"room_id": "!jEsUZKDJdhlrceRyVU:example.org",
|
|
"sender": "@example:example.org",
|
|
"origin_server_ts": 1432735824653,
|
|
"unsigned": {
|
|
"age": 1234
|
|
}
|
|
}
|
|
```
|
|
|
|
If the event is found but is not allowed to be retrieved, then a short form with
|
|
only `event_id` and `room_id` is returned with status code 200:
|
|
|
|
```
|
|
{
|
|
"event_id": "$Woq2vwLy8mNukf7e8oz61GxT5gpMmr_asNojhb56-wU",
|
|
"room_id": "!jEsUZKDJdhlrceRyVU:example.org"
|
|
}
|
|
```
|
|
|
|
If the event cannot be found on the local server and is not present on the
|
|
optionally provided servers, then return status code 404.
|
|
|
|
If the requester has been rate-limited, return status code 429 with the usual
|
|
content:
|
|
|
|
```
|
|
{
|
|
"errcode": "M_LIMIT_EXCEEDED",
|
|
"error": "Too many requests",
|
|
"retry_after_ms": 2000
|
|
}
|
|
```
|
|
|
|
## Potential issues
|
|
|
|
This proposal revives and extends a previously deprecated API. While that should
|
|
be safe given that it does not introduce breaking changes, there could be other
|
|
currently unknown complexities that result.
|
|
|
|
## Alternatives
|
|
|
|
Rather than reusing and extending an existing API, a new one could be defined
|
|
instead. If there is some reason to not revive the existing API, this may indeed
|
|
end up as the preferred approach. For the moment, reviving the existing API
|
|
seems preferable, as it already makes use of the simplest, most obvious API path
|
|
suited for this purpose.
|
|
|
|
## Security considerations
|
|
|
|
The proposed version of the API adds support for unauthenticated access. This is
|
|
a key feature of the proposal, as it is desirable to support a static matrix.to
|
|
interstitial page that may wish to query event details (assuming the user agrees
|
|
to such requests) without requiring such a page to create an authenticated
|
|
session on some server for every viewer. Supporting unauthenticated access opens
|
|
the door to possible DoS attacks by e.g. requesting every event one by one via
|
|
this API. It is therefore critical to have good rate-limiting measures in place
|
|
for both authenticated and unauthenticated requesters.
|
|
|
|
## Unstable prefix
|
|
|
|
Although this proposal revives and extends an existing API, it seems prudent to
|
|
test the revised version under the `/unstable` prefix at first, just as if it
|
|
were a fully new API.
|
|
|
|
No `unstable_features` flag is currently envisioned at this time, as it does not
|
|
seem critical to ask in advance whether a server supports the proposal.
|