matrix-spec-proposals/proposals/3715-relations-parity-messages.md

# MSC3715: Add a pagination direction parameter to `/relations`

[MSC2675](https://github.com/matrix-org/matrix-doc/pull/2675) introduced the
`/relations` API as an endpoint to paginate over the relations of an event. Unfortunately,
it is missing a `dir` parameter which is necessary to properly load thread timelines
at an arbitrary location.

Consider a long thread (e.g. consisting of 300 events), if a user receives a link
to an event somewhere in the middle it is desirable for the client to only display
a few dozen messages: the event itself and some context before and after it. As
the user scrolls additional content from the thread should be fetched.

Currently clients are forced to fetch *the entire thread* until the target
message (plus any surround context) is reached in order to implement this
functionality. A simpler implementation would allow the client to:

1. Load events in a thread backwards from a pagination token,
2. Load events in a thread forwards from a pagination token,
3. Load context around an event.

1 & 3 are currently possible; this MSC attempts to solve condition 2.

With the `dir` paraemter on `/relations, it now becomes possible for a client to:

1. Call `/context` on the target event to get a pagination token.
2. Call `/relations` twice (once with `dir=b` and once with `dir=f`) on the same
   pagination token to collect any contextual events.
3. Store the resulting pagination tokens to paginate further, if necessary.

This allows the thread to be fetched in arbitrary chunks:

```mermaid
flowchart RL
    subgraph /relations?dir=f
    $2-->$1
    end
    $1-->$0
    subgraph /context/$0
    $0
    end
    $0-->$-1
    subgraph /relations?dir=b
    $-1-->$-2
    end
```

## Proposal

It is proposed to add the `dir` parameter to the `/relations` API for parity with `/messages`.
It will [have the same as definition as for `/messages`](https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv3roomsroomidmessages),
which is copied below:

> The direction to return events from. If this is set to `f`, events will
> be returned in chronological order starting at `from`. If it is set to `b`,
> events will be returned in *reverse* chronological order, again starting at `from`.
>
> One of: `[b f]`.

In order to be backwards compatible with MSC2675 (and Synapse's legacy
implementation), the `dir` parameter must be optional (defaulting to `b`). This
differs from the specification of `/messages` where the `dir` parameter is
required.[^1]

Including the `dir` parameter will make it easier to request missing relation
information without needed to paginate through known information -- this is
particularly needed for mobile or low-bandwidth devices where it is desired to
keep the round-trips to the server to a minimum.

It is additionally useful to unify similar endpoints as much as possible to avoid
surprises for developers.

Since this endpoint can now be used to paginate backwards over children events,
it is also useful for the `from` parameter to accept `prev_batch` values from
previous calls (as well as `next_batch` values, as is currently specified). The
[definition of the `from` parameter](https://spec.matrix.org/unstable/client-server-api/#get_matrixclientv1roomsroomidrelationseventid)
is updated:

> Can be a `next_batch` token **or `prev_batch`** token from a previous call, or a
> returned `start` token from `/messages`, or a `next_batch` token from `/sync`.

(Bold indicates new text.)
## Potential issues

`/messages` does have one additional parameter (`filter`) which would still not
be implemented for `/relations`. It is unclear if this parameter is useful here.


## Alternatives

The endpoint could be replaced with the `/event_relationships` API proposed in
[MSC2836](https://github.com/matrix-org/matrix-doc/pull/2836). That API would
add significant complexity over the current `/relations` API (e.g. arbitrary
of relations) and is not necessary to simply iterate events in the reverse ordering.

Instead of having a different default direction from `/messages`, a `v2` version
could be added which accepts the `dir` parameter with the same default directionality
as `/messages`, but the opposite of the current (`v1`) version of the endpoint.


## Security considerations

None.

## Unstable prefix

Before standardization, `org.matrix.msc3715.dir` should be used in place of `dir`.

[^1]: Note that [Synapse's implementation](https://github.com/matrix-org/synapse/blob/10a88ba91cb16ccf757984f0a7d41ddf8b4dc07f/synapse/streams/config.py#L48)
does not require a `dir` parameter for the `/messages` API and defaults to `f`
if it is not provided.